@animalabs/connectome-host 0.3.1 → 0.3.7

package/src/modules/web-ui-observers.ts

@@ -0,0 +1,322 @@
+/**
+ * Observer identity for the webui — the M2 layer of connectome
+ * docs/observability.md.
+ *
+ * An observer is an Archipelago layer-0 principal: an ed25519 keypair,
+ * human device or agent or service. Authorization is a per-agent grant file
+ * (data/observers.json) that is hot-reloaded on mtime (the proven
+ * discord-filters pattern: atomic tmp+rename writes, parse errors keep the
+ * previous state) and editable by the agent itself through the observers
+ * module's tools — interiority access is a consent question, so the agent
+ * holds the pen.
+ *
+ * The handshake is challenge-less: the client signs a statement binding the
+ * Host it connected to + a fresh timestamp (replay/relay-proof, no extra
+ * round trip):
+ *
+ *   sign( "connectome-observer|v1|<host>|<timestamp>" )
+ *
+ * The server verifies signature, freshness (±5 min), and that the key has a
+ * live grant — then the connection carries that grant's scope mask.
+ */
+import { readFileSync, renameSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { createPublicKey, verify as cryptoVerify, randomBytes } from 'node:crypto';
+
+/** Scope = event-family mask. See docs/observability.md §4. */
+export const OBSERVER_SCOPES = ['health', 'ops', 'messages', 'tools', 'thinking', 'debug'] as const;
+export type ObserverScope = typeof OBSERVER_SCOPES[number];
+
+export interface ObserverGrant {
+  /** `ed25519:<base64url of the raw 32-byte public key>` */
+  key: string;
+  /** Human-readable label. Testimony, not identity — never treat as verified naming. */
+  label: string;
+  scopes: ObserverScope[];
+  /** ISO expiry; null/absent = no expiry. */
+  expires?: string | null;
+  /** Protected grants cannot be revoked via the agent-facing tools
+   *  (recipe-designated operator baseline). File edits can still remove them. */
+  protected?: boolean;
+}
+
+export interface ObserversFile {
+  observers: ObserverGrant[];
+}
+
+/** The identity envelope a client presents in its observer-hello frame. */
+export interface ObserverHelloIdentity {
+  scheme: 'ed25519';
+  /** `ed25519:<base64url raw pubkey>` — must match a grant. */
+  id: string;
+  /** base64url ed25519 signature over the bound statement. */
+  proof: string;
+  /** ISO timestamp the statement was signed at (freshness-checked). */
+  timestamp: string;
+  displayName?: string;
+}
+
+const FRESHNESS_MS = 5 * 60_000;
+
+export function observerStatement(host: string, timestamp: string): string {
+  return `connectome-observer|v1|${host}|${timestamp}`;
+}
+
+function b64urlToBuf(s: string): Buffer | null {
+  try {
+    return Buffer.from(s.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+  } catch {
+    return null;
+  }
+}
+
+/** Raw 32-byte ed25519 public key → node KeyObject (SPKI DER wrap). */
+export function ed25519PublicKey(raw: Buffer) {
+  const SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+  return createPublicKey({ key: Buffer.concat([SPKI_PREFIX, raw]), format: 'der', type: 'spki' });
+}
+
+// ---------------------------------------------------------------------------
+// File ops — the discord-mcpl filters.ts pattern, verbatim mechanics.
+// ---------------------------------------------------------------------------
+
+export function loadObserversFile(path: string): ObserversFile | null {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as ObserversFile;
+    if (!parsed || !Array.isArray(parsed.observers)) return null;
+    for (const g of parsed.observers) {
+      if (typeof g.key !== 'string' || !g.key.startsWith('ed25519:')) return null;
+      if (!Array.isArray(g.scopes)) return null;
+      if (!g.scopes.every((s) => (OBSERVER_SCOPES as readonly string[]).includes(s))) return null;
+    }
+    return parsed;
+  } catch {
+    return null; // parse/validation error → caller keeps previous (fail-safe)
+  }
+}
+
+export function saveObserversFile(path: string, file: ObserversFile): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, JSON.stringify(file, null, 2) + '\n');
+  renameSync(tmp, path); // atomic — mtime pollers never read a half-write
+}
+
+export function observersFileMtime(path: string): number | null {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+export interface VerifyResult {
+  grant: ObserverGrant;
+  scopes: Set<ObserverScope>;
+}
+
+export class ObserverRegistry {
+  private file: ObserversFile | null = null;
+  private lastMtime: number | null = null;
+  private poll: ReturnType<typeof setInterval> | null = null;
+
+  constructor(private readonly path: string) {}
+
+  start(): void {
+    this.lastMtime = observersFileMtime(this.path);
+    if (this.lastMtime !== null) {
+      this.file = loadObserversFile(this.path);
+      if (!this.file) console.error(`[webui-observers] ${this.path} unparseable — observers disabled until fixed`);
+    }
+    this.poll = setInterval(() => {
+      const m = observersFileMtime(this.path);
+      if (m === null || m === this.lastMtime) return; // missing/mid-rename or unchanged
+      this.lastMtime = m;
+      const next = loadObserversFile(this.path);
+      if (!next) {
+        console.error(`[webui-observers] ${this.path} unparseable — keeping previous grants`);
+        return;
+      }
+      this.file = next;
+      console.error(`[webui-observers] reloaded ${next.observers.length} grant(s)`);
+    }, 3000);
+    this.poll.unref();
+  }
+
+  stop(): void {
+    if (this.poll) clearInterval(this.poll);
+  }
+
+  /** True when at least one live grant exists — gates the whole feature:
+   *  no grants ⇒ webui behaves exactly as before this layer existed. */
+  active(): boolean {
+    return (this.file?.observers.length ?? 0) > 0;
+  }
+
+  grants(): ObserverGrant[] {
+    return this.file?.observers ?? [];
+  }
+
+  /**
+   * Verify an observer-hello identity envelope against the live grants.
+   * Returns the grant + scope set, or null (with a stderr reason — auth
+   * failures on a headless box must be diagnosable).
+   */
+  verifyHello(identity: ObserverHelloIdentity, hostHeader: string, now = Date.now()): VerifyResult | null {
+    const fail = (why: string): null => {
+      console.error(`[webui-observers] hello rejected (${identity?.id ?? 'no-id'}): ${why}`);
+      return null;
+    };
+    if (!identity || identity.scheme !== 'ed25519') return fail('unsupported scheme');
+    if (typeof identity.id !== 'string' || !identity.id.startsWith('ed25519:')) return fail('bad key id');
+
+    const ts = Date.parse(identity.timestamp ?? '');
+    if (!Number.isFinite(ts)) return fail('bad timestamp');
+    if (Math.abs(now - ts) > FRESHNESS_MS) return fail('stale timestamp');
+
+    const grant = this.grants().find((g) => g.key === identity.id);
+    if (!grant) return fail('no grant for key');
+    if (grant.expires && Date.parse(grant.expires) < now) return fail('grant expired');
+
+    const raw = b64urlToBuf(identity.id.slice('ed25519:'.length));
+    if (!raw || raw.length !== 32) return fail('malformed public key');
+    const sig = b64urlToBuf(identity.proof ?? '');
+    if (!sig || sig.length !== 64) return fail('malformed signature');
+
+    try {
+      const okSig = cryptoVerify(
+        null,
+        Buffer.from(observerStatement(hostHeader, identity.timestamp), 'utf8'),
+        ed25519PublicKey(raw),
+        sig,
+      );
+      if (!okSig) return fail('signature verify failed');
+    } catch (err) {
+      return fail(`verify error: ${err instanceof Error ? err.message : err}`);
+    }
+    return { grant, scopes: new Set(grant.scopes) };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Sessions — short-lived bearer tokens minted after WS auth so the SPA can
+// hit /debug/* and /healthz over plain HTTP. The WS is the authentication
+// event; HTTP rides it.
+// ---------------------------------------------------------------------------
+
+const SESSION_TTL_MS = 12 * 60 * 60_000;
+
+export class ObserverSessions {
+  private sessions = new Map<string, { scopes: Set<ObserverScope>; expiresAt: number }>();
+
+  mint(scopes: Set<ObserverScope>): string {
+    // Opportunistic sweep — the map stays tiny (one entry per WS auth).
+    const now = Date.now();
+    for (const [t, s] of this.sessions) if (s.expiresAt < now) this.sessions.delete(t);
+    const token = randomBytes(32).toString('hex');
+    this.sessions.set(token, { scopes, expiresAt: now + SESSION_TTL_MS });
+    return token;
+  }
+
+  lookup(token: string | null | undefined): Set<ObserverScope> | null {
+    if (!token) return null;
+    const s = this.sessions.get(token);
+    if (!s || s.expiresAt < Date.now()) return null;
+    return s.scopes;
+  }
+}
+
+/** Extract the observer session token from a request (cookie `fkm_obs`). */
+export function sessionTokenFromRequest(req: Request): string | null {
+  const cookie = req.headers.get('cookie');
+  if (!cookie) return null;
+  const m = /(?:^|;\s*)fkm_obs=([a-f0-9]{64})/.exec(cookie);
+  return m ? m[1]! : null;
+}
+
+// ---------------------------------------------------------------------------
+// Scope filtering — pure projections of wire data through a grant's mask
+// (docs/observability.md §4). Kept here (not in the module) so they are
+// unit-testable without the webui's process-level server singleton.
+// ---------------------------------------------------------------------------
+
+import type { WelcomeMessage, WelcomeMessageEntry } from '../web/protocol.js';
+
+/** Which scope a trace event requires. Token deltas map by blockType;
+ *  ops/mcpl lifecycle → 'ops'; usage → 'health'; the rest is conversation
+ *  lifecycle → 'messages'. */
+export function traceRequiredScope(event: { type: string }): ObserverScope {
+  const t = event.type;
+  if (t.startsWith('ops:') || t.startsWith('mcpl:')) return 'ops';
+  if (t === 'usage:updated') return 'health';
+  if (t === 'inference:tokens' || t === 'inference:content_block') {
+    const bt = (event as { blockType?: string }).blockType;
+    if (bt === 'thinking') return 'thinking';
+    if (bt === 'tool_call' || bt === 'tool_result') return 'tools';
+    return 'messages';
+  }
+  if (t.startsWith('tool:')) return 'tools';
+  return 'messages';
+}
+
+/** Project a wire entry through a scope mask: null when the observer may not
+ *  see messages at all; otherwise thinking/tool blocks are elided per scope.
+ *  Filtering, not rewriting — the wire is already typed blocks. */
+export function filterEntryForScopes(
+  entry: WelcomeMessageEntry,
+  scopes: Set<ObserverScope>,
+): WelcomeMessageEntry | null {
+  if (!scopes.has('messages')) return null;
+  if (scopes.has('thinking') && scopes.has('tools')) return entry;
+  const blocks = entry.blocks.filter((b) => {
+    if ((b.kind === 'thinking' || b.kind === 'redacted_thinking') && !scopes.has('thinking')) return false;
+    if ((b.kind === 'tool_use' || b.kind === 'tool_result') && !scopes.has('tools')) return false;
+    return true;
+  });
+  return { ...entry, blocks };
+}
+
+/** Project a welcome through an observer's scope mask. Without 'messages'
+ *  the entire conversation payload (entries + agent trees, which carry
+ *  streaming buffers) is emptied — a health/ops observer like the fleet hub
+ *  gets structure and usage, never content. Without 'health' the telemetry
+ *  fields (usage / perAgentCost / callLedger) are masked too: their live
+ *  frames (`usage`, `call-ledger`) are gated on 'health', and the welcome
+ *  must refuse exactly what the stream refuses — otherwise a messages-only
+ *  observer reads model IDs, per-call costs, and raw provider errors on
+ *  connect that it is denied a second later. */
+export function scopeWelcome(welcome: WelcomeMessage, scopes: Set<ObserverScope>): WelcomeMessage {
+  const emptyTree = { asOfTs: Date.now(), nodes: [], callIdIndex: {} };
+  const scoped: WelcomeMessage = { ...welcome };
+  if (!scopes.has('health')) {
+    delete scoped.callLedger;
+    delete scoped.perAgentCost;
+    // `usage` is required by the wire type, so it is zeroed rather than
+    // dropped (matches the emptied-not-deleted style of the fields below).
+    scoped.usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+  }
+  if (!scopes.has('messages')) {
+    return {
+      ...scoped,
+      messages: [],
+      history: { startIndex: welcome.history.totalCount, totalCount: welcome.history.totalCount },
+      localTree: emptyTree,
+      childTrees: [],
+    };
+  }
+  return {
+    ...scoped,
+    messages: welcome.messages
+      .map((e) => filterEntryForScopes(e, scopes))
+      .filter((e): e is WelcomeMessageEntry => e !== null),
+    // Agent trees replay tool calls + streaming thinking; only full
+    // interiority scopes get them.
+    ...(scopes.has('thinking') && scopes.has('tools')
+      ? {}
+      : { localTree: emptyTree, childTrees: [] }),
+  };
+}

package/src/recipe.ts

@@ -75,6 +75,10 @@ export interface RecipeStrategy {
 export interface RecipeAgent {
   name?: string;
   model?: string;
+  /** IANA zone used when rendering wall-clock times to the agent. */
+  timezone?: string;
+  /** Provider transport. Omitted preserves the historical Anthropic default. */
+  provider?: 'anthropic' | 'openai-responses';
   systemPrompt: string;
   maxTokens?: number;
   /**
@@ -86,9 +90,8 @@ export interface RecipeAgent {
   /** Per-agent context compile budget (input tokens). When unset, the
    *  ContextManager default (100k) applies. Raise for large-context models. */
   contextBudgetTokens?: number;
-  /** Prompt-cache TTL ('5m' | '1h') forwarded to the provider. Set '1h' for
-   *  agents whose reply cadence is slower than 5 minutes — avoids re-writing
-   *  the full context to cache after every gap. Unset: provider default (5m). */
+  /** Prompt-cache TTL ('5m' | '1h') forwarded to the provider. Defaults to
+   *  '1h'; set '5m' explicitly for high-frequency, sub-5-minute workloads. */
   cacheTtl?: '5m' | '1h';
   strategy?: RecipeStrategy;
   /**
@@ -100,6 +103,13 @@ export interface RecipeAgent {
     enabled: boolean;
     budgetTokens?: number;
   };
+  /** Stateless OpenAI Responses settings. Only used with
+   * `provider: "openai-responses"`. */
+  responses?: {
+    reasoningEffort?: 'none' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    reasoningContext?: 'current_turn' | 'all_turns';
+    compactThreshold?: number;
+  };
   /**
    * Content-refusal handling. When `autoRewind` is on, a `stop_reason: refusal`
    * turn triggers an automatic rewind of the triggering turn + retry (keeping
@@ -500,6 +510,7 @@ export const DEFAULT_RECIPE: Recipe = {
   description: 'General-purpose assistant with tool access',
   agent: {
     name: 'agent',
+    cacheTtl: '1h',
     systemPrompt: [
       'You are a helpful assistant. You have access to tools provided by connected MCP servers.',
       'Use them to help the user with their tasks.',
@@ -678,6 +689,39 @@ export function validateRecipe(raw: unknown): Recipe {
     throw new Error('Recipe agent must have a "systemPrompt" string');
   }
 
+  if (agent.provider !== undefined && agent.provider !== 'anthropic' && agent.provider !== 'openai-responses') {
+    throw new Error(`Recipe agent.provider must be 'anthropic' or 'openai-responses', got ${JSON.stringify(agent.provider)}.`);
+  }
+
+  if (agent.timezone !== undefined) {
+    if (typeof agent.timezone !== 'string' || !agent.timezone.trim()) {
+      throw new Error('Recipe agent.timezone must be a non-empty IANA time zone string.');
+    }
+    try {
+      new Intl.DateTimeFormat('en-US', { timeZone: agent.timezone }).format(new Date(0));
+    } catch {
+      throw new Error(`Recipe agent.timezone is not a valid IANA time zone: ${JSON.stringify(agent.timezone)}.`);
+    }
+  }
+
+  if (agent.responses !== undefined) {
+    if (!agent.responses || typeof agent.responses !== 'object' || Array.isArray(agent.responses)) {
+      throw new Error('Recipe agent.responses must be an object.');
+    }
+    const responses = agent.responses as Record<string, unknown>;
+    const efforts = ['none', 'low', 'medium', 'high', 'xhigh', 'max'];
+    if (responses.reasoningEffort !== undefined && !efforts.includes(String(responses.reasoningEffort))) {
+      throw new Error(`Invalid agent.responses.reasoningEffort ${JSON.stringify(responses.reasoningEffort)}.`);
+    }
+    if (responses.reasoningContext !== undefined && responses.reasoningContext !== 'current_turn' && responses.reasoningContext !== 'all_turns') {
+      throw new Error(`Invalid agent.responses.reasoningContext ${JSON.stringify(responses.reasoningContext)}.`);
+    }
+    if (responses.compactThreshold !== undefined &&
+        (typeof responses.compactThreshold !== 'number' || responses.compactThreshold <= 0)) {
+      throw new Error('Recipe agent.responses.compactThreshold must be a positive number.');
+    }
+  }
+
   if (agent.maxStreamTokens !== undefined && (typeof agent.maxStreamTokens !== 'number' || agent.maxStreamTokens <= 0)) {
     throw new Error('Recipe agent.maxStreamTokens must be a positive number.');
   }
@@ -687,6 +731,7 @@ export function validateRecipe(raw: unknown): Recipe {
   if (agent.cacheTtl !== undefined && agent.cacheTtl !== '5m' && agent.cacheTtl !== '1h') {
     throw new Error(`Recipe agent.cacheTtl must be '5m' or '1h', got ${JSON.stringify(agent.cacheTtl)}.`);
   }
+  agent.cacheTtl ??= '1h';
 
   // Validate agent.thinking if present. Catches typos and constraint
   // violations (notably max_tokens > budget_tokens) at recipe-load time

package/src/strategies/frontdesk-strategy.ts

@@ -9,6 +9,7 @@ import type {
   SummaryEntry,
 } from '@animalabs/context-manager';
 import type { ContentBlock } from '@animalabs/membrane';
+import { formatZonedTime, resolveTimeZone } from '@animalabs/agent-framework';
 
 // Structural mirror of AutobiographicalStrategy's internal Chunk.
 // Kept inline because @animalabs/context-manager does not currently export it.
@@ -24,7 +25,7 @@ interface Chunk {
   phaseType?: string;
 }
 
-export type FrontdeskStrategyOptions = Partial<AutobiographicalConfig>;
+export type FrontdeskStrategyOptions = Partial<AutobiographicalConfig> & { timeZone?: string };
 
 /**
  * Chatbot-flavoured context strategy for agents that receive messages via
@@ -43,6 +44,13 @@ export class FrontdeskStrategy extends AutobiographicalStrategy {
   override readonly name: string = 'frontdesk';
 
   private salientSourceIds: Set<string> = new Set();
+  private readonly timeZone: string;
+
+  constructor(options: FrontdeskStrategyOptions = {}) {
+    const { timeZone, ...strategyOptions } = options;
+    super(strategyOptions);
+    this.timeZone = resolveTimeZone(timeZone);
+  }
 
   override select(
     store: MessageStoreView,
@@ -146,9 +154,7 @@ export class FrontdeskStrategy extends AutobiographicalStrategy {
     }
     if (!d && msgTs instanceof Date && !isNaN(msgTs.getTime())) d = msgTs;
     if (!d) return null;
-    const hh = String(d.getHours()).padStart(2, '0');
-    const mm = String(d.getMinutes()).padStart(2, '0');
-    return `${hh}:${mm}`;
+    return formatZonedTime(d, this.timeZone);
   }
 
   // ==========================================================================

package/src/web/protocol.ts

@@ -93,6 +93,9 @@ export interface WelcomeMessage {
   /** Per-agent cost breakdown for the parent process, present when the
    *  framework's usage tracker has data. Empty during cold start. */
   perAgentCost?: PerAgentCost[];
+  /** Recent provider calls with cache verdicts. Present when the host's
+   *  provider adapter exposes the call ledger. */
+  callLedger?: CallLedgerSnapshot;
 }
 
 /**
@@ -164,6 +167,91 @@ export interface UsageMessage {
   perAgentCost?: PerAgentCost[];
 }
 
+/** Live replacement snapshot emitted after each provider call. */
+export interface CallLedgerMessage {
+  type: 'call-ledger';
+  ledger: CallLedgerSnapshot;
+}
+
+export type CallLedgerVerdict =
+  | 'HIT'
+  | 'hit+extend'
+  | 'uncached'
+  | 'rewrite:expired'
+  | 'rewrite:prefix-mutated'
+  | 'rewrite:prefix-truncated'
+  | 'rewrite:unexplained'
+  | 'first-write'
+  | 'ERROR'
+  | 'empty'
+  | 'unknown';
+
+export interface CallLedgerRow {
+  id: string;
+  timestamp: string;
+  kind: 'complete' | 'stream';
+  /** Honest call-class estimate; `~` means the trigger plumbing did not
+   *  provide a definitive origin. */
+  originEstimate: 'turn~' | 'aux~';
+  model: string;
+  messages: number;
+  durationMs: number;
+  tokens: { input: number; output: number; cacheRead: number; cacheWrite: number };
+  cost?: CallCostBreakdown;
+  cache: {
+    /** Undefined for older compact logs that predate marker summaries. */
+    breakpoints?: number;
+    ttls: string[];
+    effectiveTtl: '5m' | '1h';
+  };
+  verdict: CallLedgerVerdict;
+  cause: string;
+  stopReason?: string;
+  error?: string;
+}
+
+export interface CallCostBreakdown {
+  input: number;
+  cacheWrite5m: number;
+  cacheWrite1h: number;
+  cacheRead: number;
+  output: number;
+  total: number;
+  currency: 'USD';
+  /** `billing` means every charged usage bucket and pricing modifier was
+   *  known. Unknown/mixed buckets are left unpriced rather than estimated. */
+  grade: 'billing';
+  pricingVersion: string;
+  rates: {
+    inputPerMillion: number;
+    outputPerMillion: number;
+    cacheWrite5mPerMillion: number;
+    cacheWrite1hPerMillion: number;
+    cacheReadPerMillion: number;
+  };
+}
+
+export interface CallLedgerSnapshot {
+  /** Oldest to newest; clients may reverse for display. */
+  rows: CallLedgerRow[];
+  summary: {
+    calls: number;
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cacheHitRatio: number;
+    cost?: {
+      total: number;
+      currency: 'USD';
+      pricedCalls: number;
+      unpricedCalls: number;
+      pricingVersion: string;
+    };
+    byVerdict: Partial<Record<CallLedgerVerdict, number>>;
+  };
+}
+
 export interface TokenUsage {
   input: number;
   output: number;
@@ -352,6 +440,7 @@ export type WebUiServerMessage =
   | ChildEventMessage
   | CommandResultMessage
   | UsageMessage
+  | CallLedgerMessage
   | BranchChangedMessage
   | SessionChangedMessage
   | PeekMessage
@@ -364,8 +453,35 @@ export type WebUiServerMessage =
   | WorkspaceFileMessage
   | HistoryPageMessage
   | MessageAppendedMessage
+  | ObserverAuthRequiredMessage
+  | ObserverAckMessage
   | ErrorMessage;
 
+// ---------------------------------------------------------------------------
+// Observer identity (docs/observability.md M2) — additive to protocol v1.
+// Basic-auth clients never see these frames; key-authenticated observers
+// authenticate in-band over the WS before any data flows.
+// ---------------------------------------------------------------------------
+
+/** Sent to a connection that upgraded without basic auth (allowed only when
+ *  observer grants exist): the client must reply with observer-hello before
+ *  anything else is sent. `host` is what the server will verify the signed
+ *  statement against — the Host header of the upgrade request. */
+export interface ObserverAuthRequiredMessage {
+  type: 'observer-auth-required';
+  host: string;
+}
+
+/** Successful observer authentication. `sessionToken` is a short-lived
+ *  bearer for HTTP routes (set as the `fkm_obs` cookie by the SPA);
+ *  `scopes` is the grant's mask — the SPA adapts its UI to it. */
+export interface ObserverAckMessage {
+  type: 'observer-ack';
+  scopes: string[];
+  sessionToken: string;
+  label: string;
+}
+
 // ---------------------------------------------------------------------------
 // Client → Server
 // ---------------------------------------------------------------------------
@@ -522,8 +638,26 @@ export interface RequestHistoryMessage {
   limit?: number;
 }
 
+/** In-band observer authentication (docs/observability.md §3): the client
+ *  signs `connectome-observer|v1|<host>|<timestamp>` with its ed25519 key.
+ *  Challenge-less — the Host binding + freshness window replace a nonce. */
+export interface ObserverHelloMessage {
+  type: 'observer-hello';
+  identity: {
+    scheme: 'ed25519';
+    /** `ed25519:<base64url raw 32-byte public key>` */
+    id: string;
+    /** base64url signature over the bound statement. */
+    proof: string;
+    /** ISO timestamp used in the statement (±5 min freshness). */
+    timestamp: string;
+    displayName?: string;
+  };
+}
+
 export type WebUiClientMessage =
   | UserMessageMessage
+  | ObserverHelloMessage
   | RequestHistoryMessage
   | CommandMessage
   | RouteToChildMessage
@@ -565,6 +699,13 @@ export function isClientMessage(value: unknown): value is WebUiClientMessage {
       return true;
     case 'user-message':
       return typeof v.content === 'string';
+    case 'observer-hello': {
+      const id = v.identity as Record<string, unknown> | undefined;
+      return !!id && id.scheme === 'ed25519'
+        && typeof id.id === 'string'
+        && typeof id.proof === 'string'
+        && typeof id.timestamp === 'string';
+    }
     case 'command':
       return typeof v.command === 'string'
         && (v.corrId === undefined || typeof v.corrId === 'string');