@animalabs/connectome-host 0.3.1

package/src/logging-adapter.ts

@@ -0,0 +1,208 @@
+// AnthropicAdapter wrapper that appends each LLM call's RAW request, RAW
+// response, and any error to a JSONL log file. Restores the Hermes-era
+// `llm-calls.<iso>.jsonl` visibility we lose on the connectome stack by
+// default. Successful calls keep a compact request summary; the full raw
+// request is retained only for refusals and errors, where forensic inspection
+// matters. Serializing the full raw + normalized request on every tool-loop
+// turn previously created several simultaneous copies of a large context and
+// contributed to production OOMs.
+//
+// "Raw" means the actual Anthropic API payload (post-buildRequest, including
+// `thinking`, tool definitions in Anthropic shape, etc.) and the raw provider
+// response — not the membrane-normalized intermediate. We hook the membrane's
+// `options.onRequest` callback (called inside anthropic.ts with the built
+// request) and read `ProviderResponse.raw` for the response. Normalized
+// representations are kept under separate keys for occasional cross-reference.
+//
+// One file per process lifetime (timestamped at construction). Each line is a
+// JSON object with shape:
+//   { type: 'call'|'error', kind: 'complete'|'stream', timestamp, durationMs,
+//     requestSummary, rawRequest?, rawResponse, error? }
+
+import { AnthropicAdapter } from '@animalabs/membrane';
+import type {
+  ProviderRequest,
+  ProviderResponse,
+  ProviderRequestOptions,
+  StreamCallbacks,
+} from '@animalabs/membrane';
+import { appendFileSync } from 'node:fs';
+
+/** Live read of the current reasoning setting. The host wires this to
+ *  `SettingsModule.getReasoning()` so toggles via the `settings--reasoning_*`
+ *  tools take effect on the next call without restart. */
+export type ReasoningGetter = () => { enabled: boolean; budgetTokens: number };
+
+/** Exact first-system-block identity Anthropic requires on subscription
+ *  (sk-ant-oat…) OAuth traffic. Verified 2026-07-09: any other first block —
+ *  including this text with a suffix appended in the SAME block — is rejected
+ *  with a masked 429 rate_limit_error; this block followed by arbitrary
+ *  persona blocks is accepted (the mechanism the Agent SDK's
+ *  system-prompt-append uses). */
+const OAUTH_SYSTEM_IDENTITY = "You are Claude Code, Anthropic's official CLI for Claude.";
+
+export class LoggingAnthropicAdapter extends AnthropicAdapter {
+  private readonly logPath: string;
+  private readonly getReasoning?: ReasoningGetter;
+  /** True when authenticated with an OAuth/Bearer token instead of an API
+   *  key; requests then need the identity block prepended (see above). */
+  private readonly oauthMode: boolean;
+
+  constructor(
+    config: ConstructorParameters<typeof AnthropicAdapter>[0],
+    logPath: string,
+    getReasoning?: ReasoningGetter,
+  ) {
+    super(config);
+    this.logPath = logPath;
+    this.getReasoning = getReasoning;
+    this.oauthMode = Boolean(config?.authToken);
+  }
+
+  /** Under OAuth subscription auth, prepend the required identity block to the
+   *  system prompt (converting a string system to blocks). No-op under API-key
+   *  auth or when the identity block is already first. The block is plain
+   *  (no cache_control) and a stable prefix, so caching is unaffected. */
+  private withOAuthIdentity(request: ProviderRequest): ProviderRequest {
+    if (!this.oauthMode) return request;
+    const sys = request.system;
+    const blocks: unknown[] =
+      typeof sys === 'string' && sys.length > 0
+        ? [{ type: 'text', text: sys }]
+        : Array.isArray(sys) ? sys : [];
+    const first = blocks[0] as { type?: string; text?: string } | undefined;
+    if (first?.type === 'text' && first.text === OAUTH_SYSTEM_IDENTITY) return request;
+    return {
+      ...request,
+      system: [{ type: 'text', text: OAUTH_SYSTEM_IDENTITY }, ...blocks],
+    };
+  }
+
+  /** If reasoning is enabled, inject `thinking` into the request before the
+   *  adapter builds the Anthropic payload. The Anthropic adapter forwards
+   *  provider-specific params carried in `request.extra`, so that's the hook
+   *  point. We return a shallow clone to avoid surprising callers. */
+  private withReasoning(request: ProviderRequest): ProviderRequest {
+    const r = this.getReasoning?.();
+    if (!r || !r.enabled) return request;
+    // Use ADAPTIVE thinking, not the legacy { type:'enabled', budget_tokens }
+    // form. Current Anthropic models (opus-4-6/4-7/4-8, …) reject the legacy
+    // form with: `"thinking.type.enabled" is not supported for this model.
+    // Use "thinking.type.adaptive"`. Under adaptive the model sizes its own
+    // thinking, so `budgetTokens` is no longer sent (it still shows in
+    // reasoning_status as an informational hint).
+    //
+    // membrane's `ProviderRequest` doesn't type a top-level `thinking` field
+    // (membrane is 0.5.68 — agent-framework is the package that went 0.6.0;
+    // the old `as … ProviderRequest['thinking']` cast only ever compiled via a
+    // stale nested membrane copy that lockfile dedup removed). But the Anthropic
+    // adapter applies `request.extra` to the API params verbatim
+    // (`complete()`: `const { normalizedMessages, prompt, ...rest } =
+    // request.extra; Object.assign(params, rest)`), so we route thinking
+    // through the typed `extra` bag — no type assertion, and it survives the
+    // next dependency reshuffle instead of hiding it from the compiler.
+    return {
+      ...request,
+      extra: { ...request.extra, thinking: { type: 'adaptive' } },
+    };
+  }
+
+  private log(record: Record<string, unknown>): void {
+    try {
+      appendFileSync(this.logPath, JSON.stringify(record) + '\n');
+    } catch {
+      // never throw from logging
+    }
+  }
+
+  private requestSummary(request: ProviderRequest): Record<string, unknown> {
+    return {
+      model: request.model,
+      maxTokens: request.maxTokens,
+      messages: request.messages.length,
+      tools: request.tools?.length ?? 0,
+    };
+  }
+
+  private refusalRawRequest(response: ProviderResponse, rawRequest: unknown): unknown {
+    const raw = (response as { raw?: { stop_reason?: string } }).raw;
+    return raw?.stop_reason === 'refusal' ? rawRequest : undefined;
+  }
+
+  /** Wrap options to capture the raw provider request via the membrane
+   *  onRequest hook, then chain to any caller-supplied onRequest. */
+  private captureRawRequest(
+    options: ProviderRequestOptions | undefined,
+    sink: { rawRequest: unknown },
+  ): ProviderRequestOptions {
+    const callerOnRequest = options?.onRequest;
+    return {
+      ...options,
+      onRequest: (req: unknown) => {
+        sink.rawRequest = req;
+        try { callerOnRequest?.(req as never); } catch { /* never block on caller hook */ }
+      },
+    } as ProviderRequestOptions;
+  }
+
+  override async complete(
+    request: ProviderRequest,
+    options?: ProviderRequestOptions,
+  ): Promise<ProviderResponse> {
+    const t0 = Date.now();
+    const effective = this.withOAuthIdentity(this.withReasoning(request));
+    const sink: { rawRequest: unknown } = { rawRequest: null };
+    const wrapped = this.captureRawRequest(options, sink);
+    try {
+      const response = await super.complete(effective, wrapped);
+      this.log({
+        type: 'call', kind: 'complete',
+        timestamp: new Date().toISOString(), durationMs: Date.now() - t0,
+        requestSummary: this.requestSummary(request),
+        rawRequest: this.refusalRawRequest(response, sink.rawRequest),
+        rawResponse: (response as { raw?: unknown }).raw ?? null,
+      });
+      return response;
+    } catch (err) {
+      this.log({
+        type: 'error', kind: 'complete',
+        timestamp: new Date().toISOString(), durationMs: Date.now() - t0,
+        requestSummary: this.requestSummary(request),
+        rawRequest: sink.rawRequest,
+        error: err instanceof Error ? { name: err.name, message: err.message, stack: err.stack } : String(err),
+      });
+      throw err;
+    }
+  }
+
+  override async stream(
+    request: ProviderRequest,
+    callbacks: StreamCallbacks,
+    options?: ProviderRequestOptions,
+  ): Promise<ProviderResponse> {
+    const t0 = Date.now();
+    const effective = this.withOAuthIdentity(this.withReasoning(request));
+    const sink: { rawRequest: unknown } = { rawRequest: null };
+    const wrapped = this.captureRawRequest(options, sink);
+    try {
+      const response = await super.stream(effective, callbacks, wrapped);
+      this.log({
+        type: 'call', kind: 'stream',
+        timestamp: new Date().toISOString(), durationMs: Date.now() - t0,
+        requestSummary: this.requestSummary(request),
+        rawRequest: this.refusalRawRequest(response, sink.rawRequest),
+        rawResponse: (response as { raw?: unknown }).raw ?? null,
+      });
+      return response;
+    } catch (err) {
+      this.log({
+        type: 'error', kind: 'stream',
+        timestamp: new Date().toISOString(), durationMs: Date.now() - t0,
+        requestSummary: this.requestSummary(request),
+        rawRequest: sink.rawRequest,
+        error: err instanceof Error ? { name: err.name, message: err.message, stack: err.stack } : String(err),
+      });
+      throw err;
+    }
+  }
+}

package/src/mcpl-config.ts

@@ -0,0 +1,199 @@
+/**
+ * File-driven MCPL server configuration.
+ *
+ * Reads/writes `mcpl-servers.json` (CC `.mcp.json` shape), keyed by server ID.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+
+/** Default config file path, resolved from cwd. */
+export const DEFAULT_CONFIG_PATH = resolve(process.cwd(), 'mcpl-servers.json');
+
+/**
+ * Serializable subset of McplServerConfig (everything except callbacks and scopes).
+ */
+export interface ServerFileEntry {
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+  toolPrefix?: string;
+  reconnect?: boolean;
+  reconnectIntervalMs?: number;
+  reconnectMaxIntervalMs?: number;
+  enabledFeatureSets?: string[];
+  disabledFeatureSets?: string[];
+  enabledTools?: string[];
+  disabledTools?: string[];
+  channelSubscription?: 'auto' | 'manual' | string[];
+}
+
+export interface McplServersFile {
+  mcplServers: Record<string, ServerFileEntry>;
+}
+
+/** A loaded server config — serializable fields plus the id from the key. */
+export type LoadedServerConfig = ServerFileEntry & { id: string };
+
+/**
+ * Load MCPL server configs from a JSON file.
+ * Returns empty array if the file doesn't exist.
+ * Resolves relative paths in `args` relative to the config file's directory.
+ */
+export function loadMcplServers(configPath: string): LoadedServerConfig[] {
+  if (!existsSync(configPath)) return [];
+
+  const raw = readFileSync(configPath, 'utf-8');
+  const parsed = JSON.parse(raw) as McplServersFile;
+  if (!parsed.mcplServers || typeof parsed.mcplServers !== 'object') return [];
+
+  const configDir = dirname(resolve(configPath));
+  const servers: LoadedServerConfig[] = [];
+
+  for (const [id, entry] of Object.entries(parsed.mcplServers)) {
+    const args = entry.args?.map(arg => {
+      // Resolve relative paths (starting with ./ or ../) relative to config dir
+      if (arg.startsWith('./') || arg.startsWith('../')) {
+        return resolve(configDir, arg);
+      }
+      return arg;
+    });
+
+    servers.push({
+      id,
+      command: entry.command,
+      args,
+      env: entry.env,
+      toolPrefix: entry.toolPrefix,
+      reconnect: entry.reconnect,
+      reconnectIntervalMs: entry.reconnectIntervalMs,
+      reconnectMaxIntervalMs: entry.reconnectMaxIntervalMs,
+      enabledFeatureSets: entry.enabledFeatureSets,
+      disabledFeatureSets: entry.disabledFeatureSets,
+      enabledTools: entry.enabledTools,
+      disabledTools: entry.disabledTools,
+      channelSubscription: entry.channelSubscription,
+    });
+  }
+
+  return servers;
+}
+
+// ---------------------------------------------------------------------------
+// Agent overlay — servers the agent deployed/unloaded for itself at runtime
+// ---------------------------------------------------------------------------
+
+/** Default agent-owned overlay path, resolved from cwd (per-agent deploy dir). */
+export const DEFAULT_AGENT_OVERLAY_PATH = resolve(process.cwd(), 'mcpl-servers.agent.json');
+
+/**
+ * An overlay entry is either a full server definition (agent-deployed, loads
+ * unconditionally — no recipe opt-in needed) or a tombstone `{disabled: true}`
+ * that suppresses a recipe/file server the agent unloaded.
+ *
+ * Unlike `ServerFileEntry`, `command` is optional here: an entry has EITHER
+ * a `command` (stdio) or a `url` (WebSocket), and tombstones have neither.
+ */
+export interface AgentOverlayEntry extends Partial<ServerFileEntry> {
+  /** WebSocket URL (WebSocket transport). Mutually exclusive with command. */
+  url?: string;
+  transport?: 'stdio' | 'websocket';
+  /** Bearer token for WebSocket auth. */
+  token?: string;
+  /** Tombstone: suppress a recipe/file server the agent unloaded. */
+  disabled?: boolean;
+}
+
+export interface AgentOverlayFile {
+  mcplServers: Record<string, AgentOverlayEntry>;
+}
+
+/** Read the agent overlay file. Returns empty object if it doesn't exist. */
+export function readAgentOverlay(overlayPath: string): Record<string, AgentOverlayEntry> {
+  if (!existsSync(overlayPath)) return {};
+  const raw = readFileSync(overlayPath, 'utf-8');
+  const parsed = JSON.parse(raw) as AgentOverlayFile;
+  return parsed.mcplServers ?? {};
+}
+
+/** Write the agent overlay file. */
+export function saveAgentOverlay(
+  overlayPath: string,
+  servers: Record<string, AgentOverlayEntry>,
+): void {
+  const data: AgentOverlayFile = { mcplServers: servers };
+  writeFileSync(overlayPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Resolve an overlay entry into a server config object (id + fields, relative
+ * `./`/`../` args resolved against the overlay file's directory). Returns
+ * null for tombstones and entries with neither command nor url.
+ */
+export function resolveOverlayEntry(
+  id: string,
+  entry: AgentOverlayEntry,
+  overlayPath: string,
+): ({ id: string; command?: string; url?: string } & Record<string, unknown>) | null {
+  if (entry.disabled) return null;
+  if (!entry.command && !entry.url) return null;
+  const overlayDir = dirname(resolve(overlayPath));
+  const { disabled: _d, ...fields } = entry;
+  return {
+    id,
+    ...fields,
+    ...(entry.args
+      ? {
+          args: entry.args.map(arg =>
+            arg.startsWith('./') || arg.startsWith('../') ? resolve(overlayDir, arg) : arg,
+          ),
+        }
+      : {}),
+  };
+}
+
+/**
+ * Apply the agent overlay to a resolved server list:
+ *   - tombstones (`disabled: true`) remove the matching server
+ *   - full entries replace an existing server or append a new one
+ * Relative `./`/`../` args are resolved against the overlay file's directory.
+ */
+export function applyAgentOverlay<T extends { id: string }>(
+  servers: T[],
+  overlayPath: string,
+): Array<T | ({ id: string } & Record<string, unknown>)> {
+  const overlay = readAgentOverlay(overlayPath);
+  if (Object.keys(overlay).length === 0) return servers;
+
+  const result: Array<T | ({ id: string } & Record<string, unknown>)> =
+    servers.filter(s => overlay[s.id]?.disabled !== true);
+
+  for (const [id, entry] of Object.entries(overlay)) {
+    const loaded = resolveOverlayEntry(id, entry, overlayPath);
+    if (!loaded) continue;
+    const idx = result.findIndex(s => s.id === id);
+    if (idx >= 0) result[idx] = loaded;
+    else result.push(loaded);
+  }
+
+  return result;
+}
+
+/**
+ * Read the raw server entries from the config file (for editing).
+ * Returns empty object if file doesn't exist.
+ */
+export function readMcplServersFile(configPath: string): Record<string, ServerFileEntry> {
+  if (!existsSync(configPath)) return {};
+  const raw = readFileSync(configPath, 'utf-8');
+  const parsed = JSON.parse(raw) as McplServersFile;
+  return parsed.mcplServers ?? {};
+}
+
+/**
+ * Write server entries to the config file.
+ */
+export function saveMcplServers(configPath: string, servers: Record<string, ServerFileEntry>): void {
+  const data: McplServersFile = { mcplServers: servers };
+  writeFileSync(configPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}

package/src/modules/activity-module.ts

@@ -0,0 +1,270 @@
+/**
+ * ActivityModule — surfaces agent composition activity (typing indicators)
+ * to a configurable set of MCPL channels while inference is active.
+ *
+ * Recipe-seeded initial channels; agent can add/remove at runtime via tools.
+ * State persists via Chronicle. Typing refresh is owned by the framework's
+ * ChannelRegistry (~7s interval, matches Discord/Zulip expiry).
+ */
+
+import type {
+  AgentFramework,
+  Module,
+  ModuleContext,
+  ProcessEvent,
+  ProcessState,
+  EventResponse,
+  ToolDefinition,
+  ToolCall,
+  ToolResult,
+  TraceEvent,
+  WorkspaceModule,
+} from '@animalabs/agent-framework';
+import { open } from 'node:fs/promises';
+
+export interface ActivityModuleConfig {
+  initialChannels?: string[];
+}
+
+interface ActivityState {
+  channels: string[];
+}
+
+/**
+ * Parse a loose origin hint out of a file's top lines. Used when an inference
+ * is triggered by a workspace file rather than an incoming channel message:
+ * if the file's head declares the conversation it's replying to, we route the
+ * typing indicator to that topic. Returns null if no hint is found.
+ *
+ * Recognized shapes:
+ *   - `origin: zulip#<channel>#<topic>`
+ *   - `reply-to: zulip:<channel>/<topic>`
+ *   - YAML frontmatter (delimited by leading `---` ... `---`) containing both
+ *     `channel: <name>` and `topic: <name>` — matches the clerk's existing
+ *     knowledge-request ticket convention. Loose `channel:`/`topic:` lines
+ *     outside a frontmatter block are ignored to avoid mis-routing on prose
+ *     files (e.g. README headings, mined artifacts quoting Zulip metadata).
+ *
+ * All platform hints currently resolve to `zulip:<channel>` — extend here when
+ * another MCPL server wants in on origin-routing.
+ */
+function parseOriginHint(text: string): { channelId: string; topic: string } | null {
+  const compact = text.match(/origin:\s*zulip#([^\s#]+)#(\S+)/i);
+  if (compact) return { channelId: `zulip:${compact[1]}`, topic: compact[2] };
+
+  const replyTo = text.match(/reply-to:\s*zulip:([^\s/]+)\/(\S+)/i);
+  if (replyTo) return { channelId: `zulip:${replyTo[1]}`, topic: replyTo[2] };
+
+  const frontmatter = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (frontmatter) {
+    const block = frontmatter[1];
+    const channelMatch = block.match(/^channel:\s*(\S+)\s*$/m);
+    const topicMatch = block.match(/^topic:\s*(.+?)\s*$/m);
+    if (channelMatch && topicMatch) {
+      return { channelId: `zulip:${channelMatch[1]}`, topic: topicMatch[1] };
+    }
+  }
+
+  return null;
+}
+
+export class ActivityModule implements Module {
+  readonly name = 'activity';
+
+  private ctx: ModuleContext | null = null;
+  private framework: AgentFramework | null = null;
+  private channels = new Set<string>();
+  private typingActive = false;
+
+  /** Most recent incoming-message metadata per channel. Handed back to the
+   *  originating server on each typing notification so routing hints (e.g.
+   *  Zulip topic) land where the conversation is active. */
+  private lastMetadata = new Map<string, Record<string, unknown>>();
+
+  constructor(private readonly config: ActivityModuleConfig = {}) {}
+
+  async start(ctx: ModuleContext): Promise<void> {
+    this.ctx = ctx;
+
+    const saved = ctx.getState<ActivityState>();
+    if (saved?.channels) {
+      this.channels = new Set(saved.channels);
+    } else if (this.config.initialChannels && this.config.initialChannels.length > 0) {
+      this.channels = new Set(this.config.initialChannels);
+      this.persist();
+    }
+  }
+
+  async stop(): Promise<void> {
+    this.stopAllTyping();
+    this.ctx = null;
+    this.framework = null;
+  }
+
+  /** Called from the host after framework creation, like SubagentModule. */
+  setFramework(framework: AgentFramework): void {
+    this.framework = framework;
+    framework.onTrace((event: TraceEvent) => {
+      if (event.type === 'inference:started') this.onInferenceStarted();
+      else if (event.type === 'inference:completed') this.onInferenceCompleted();
+    });
+  }
+
+  getTools(): ToolDefinition[] {
+    return [
+      {
+        name: 'show_in',
+        description:
+          'Subscribe a channel to your composition-activity indicator (e.g. Zulip "is typing"). ' +
+          'This is a SET-AND-FORGET POLICY — call it once to opt a channel in, and the host will ' +
+          'automatically start the indicator before each inference and stop it when the inference ' +
+          'ends. You do NOT need to call this before each reply. Do NOT bracket messages with ' +
+          'show_in / send / hide_in — that pattern produces confusing UX because message sends ' +
+          'do not clear Zulip typing indicators, so you end up flashing your own indicator on and ' +
+          'off unnecessarily. Use hide_in only if you want to permanently stop indicating in that ' +
+          'channel. Channel IDs use the MCPL format, e.g. "zulip:tracker-miner-f". Idempotent.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            channel: { type: 'string', description: 'MCPL channel id' },
+          },
+          required: ['channel'],
+        },
+      },
+      {
+        name: 'hide_in',
+        description:
+          'Unsubscribe a channel from your composition-activity indicator. Use this ONLY when you ' +
+          'want to PERMANENTLY stop surfacing your activity in that channel (e.g. if a user asks ' +
+          'you to, or you decide the channel should no longer see your thinking). Do NOT call this ' +
+          'after sending a message in a normal reply flow — the host already stops the indicator ' +
+          "when inference completes. Doesn't affect other channels. Idempotent.",
+        inputSchema: {
+          type: 'object',
+          properties: {
+            channel: { type: 'string', description: 'MCPL channel id' },
+          },
+          required: ['channel'],
+        },
+      },
+    ];
+  }
+
+  async handleToolCall(call: ToolCall): Promise<ToolResult> {
+    const channel = typeof (call.input as { channel?: unknown }).channel === 'string'
+      ? ((call.input as { channel: string }).channel)
+      : null;
+    if (!channel) {
+      return { success: false, isError: true, error: 'channel (string) is required' };
+    }
+
+    if (call.name === 'show_in') {
+      const added = !this.channels.has(channel);
+      this.channels.add(channel);
+      this.persist();
+      if (this.typingActive) {
+        this.framework?.channels?.startTyping(channel, this.lastMetadata.get(channel));
+      }
+      return {
+        success: true,
+        data: added
+          ? `Now showing composition activity in ${channel}.`
+          : `Already showing composition activity in ${channel}.`,
+      };
+    }
+
+    if (call.name === 'hide_in') {
+      const removed = this.channels.delete(channel);
+      this.persist();
+      this.framework?.channels?.stopTyping(channel);
+      return {
+        success: true,
+        data: removed
+          ? `No longer showing composition activity in ${channel}.`
+          : `Was not showing composition activity in ${channel}.`,
+      };
+    }
+
+    return { success: false, isError: true, error: `Unknown tool: ${call.name}` };
+  }
+
+  async onProcess(event: ProcessEvent, _state: ProcessState): Promise<EventResponse> {
+    // Track the most recent incoming-message metadata per channel so typing
+    // notifications can echo it back to the originating server as routing hints.
+    if (event.type === 'mcpl:channel-incoming') {
+      const e = event as unknown as {
+        channelId: string;
+        threadId?: string;
+        metadata?: Record<string, unknown>;
+      };
+      const merged: Record<string, unknown> = { ...(e.metadata ?? {}) };
+      if (e.threadId !== undefined && merged.threadId === undefined) {
+        merged.threadId = e.threadId;
+      }
+      this.lastMetadata.set(e.channelId, merged);
+    }
+    // Workspace-triggered inferences have no incoming-message metadata, so
+    // peek at the file's head for an origin hint and populate routing metadata
+    // if found. Best-effort; failures are silent.
+    else if (event.type === 'workspace:created' || event.type === 'workspace:modified') {
+      const e = event as unknown as { paths: string[] };
+      await this.extractOriginFromFiles(e.paths);
+    }
+    return {};
+  }
+
+  private async extractOriginFromFiles(mountPaths: string[]): Promise<void> {
+    const workspace = this.ctx?.getModule<WorkspaceModule>('workspace');
+    if (!workspace) return;
+
+    for (const mountPath of mountPaths) {
+      const abs = workspace.resolveAbsolutePath(mountPath);
+      if (!abs) continue;
+
+      try {
+        const fd = await open(abs, 'r');
+        try {
+          const buf = Buffer.alloc(2048);
+          const { bytesRead } = await fd.read(buf, 0, buf.length, 0);
+          const head = buf.toString('utf8', 0, bytesRead);
+
+          const origin = parseOriginHint(head);
+          if (origin && this.channels.has(origin.channelId)) {
+            // Merge with any existing metadata so other keys (e.g. senderEmail)
+            // survive if the origin refresh is subsequent to an incoming message.
+            const prior = this.lastMetadata.get(origin.channelId) ?? {};
+            this.lastMetadata.set(origin.channelId, { ...prior, topic: origin.topic });
+          }
+        } finally {
+          await fd.close();
+        }
+      } catch {
+        // File unreadable / gone / etc. — silently skip.
+      }
+    }
+  }
+
+  private onInferenceStarted(): void {
+    this.typingActive = true;
+    const registry = this.framework?.channels;
+    if (!registry) return;
+    for (const ch of this.channels) {
+      registry.startTyping(ch, this.lastMetadata.get(ch));
+    }
+  }
+
+  private onInferenceCompleted(): void {
+    this.typingActive = false;
+    this.stopAllTyping();
+  }
+
+  private stopAllTyping(): void {
+    const registry = this.framework?.channels;
+    if (!registry) return;
+    for (const ch of this.channels) registry.stopTyping(ch);
+  }
+
+  private persist(): void {
+    this.ctx?.setState<ActivityState>({ channels: [...this.channels] });
+  }
+}