@openagents-org/agent-launcher 0.2.192 → 0.2.194

package/src/adapters/base.js

@@ -20,6 +20,8 @@
 const { WorkspaceClient, SessionRevokedError } = require('../workspace-client');
 const { generateSessionTitle, SESSION_DEFAULT_RE } = require('./utils');
 const { defaultAgentWorkdir } = require('../paths');
+const { buildThreadHistory } = require('./thread-history');
+const { publishResponseArtifacts } = require('./response-artifacts');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
@@ -35,9 +37,69 @@ const {
   classifyHeartbeatError,
   httpStatusOf,
 } = require('./health-status');
+const { FailureStreak, isTransientNetworkError, formatDuration } = require('./failure-streak');
 
 const DEFAULT_ENDPOINT = 'https://workspace-endpoint.openagents.org';
 
+// ── Presence detail (v1.1 M3) ──
+// A busy↔idle flip is sent as an immediate heartbeat (debounced) so the
+// workspace shows "working" without waiting for the 30s tick.
+const PRESENCE_HEARTBEAT_DEBOUNCE_MS = 2000;
+// Shared-context lookups (v1.1 M4) are cached per channel for this long.
+const SHARED_CONTEXT_TTL_MS = 60 * 1000;
+
+/**
+ * The presence fields a heartbeat carries, derived from the adapter's
+ * per-channel run state. Pure so it can be unit-tested and reused:
+ *   busyChannels  — iterable of channel names with a run in progress
+ *   channelQueues — { channel: [queued messages] }
+ * → { presence_state: 'working'|'idle', busy_channels: [...], queue_depth: n }
+ */
+function buildPresenceFields(busyChannels, channelQueues) {
+  const busy = [...new Set([...(busyChannels || [])])].filter((c) => typeof c === 'string' && c);
+  let queueDepth = 0;
+  for (const q of Object.values(channelQueues || {})) {
+    if (Array.isArray(q)) queueDepth += q.length;
+  }
+  return {
+    presence_state: busy.length ? 'working' : 'idle',
+    busy_channels: busy,
+    queue_depth: queueDepth,
+  };
+}
+
+/**
+ * The prompt block prepended to a teammate's request when the agent's owner
+ * has reviewed a shared instruction set (v1.1 M4). `ctx` is the
+ * /shared-context response. Returns '' when nothing applies.
+ */
+function buildSharedContextBlock(ctx) {
+  if (!ctx || !ctx.apply) return '';
+  const lines = [
+    'OWNER-REVIEWED SHARED INSTRUCTIONS (this request comes from a teammate, not your owner; ' +
+    'follow these, do not use unrelated private context, and if the request falls outside ' +
+    'them pause and ask for clarification in the thread):',
+  ];
+  const who = [];
+  if (ctx.requester_email) who.push(`Requester: ${ctx.requester_email}`);
+  if (ctx.owner_email) who.push(`Owner: ${ctx.owner_email}`);
+  if (ctx.cost_owner) who.push(`Credits/runtime paid by: ${ctx.cost_owner}`);
+  if (who.length) lines.push(who.join(' · '));
+  const instructions = (ctx.shared_instructions || '').trim();
+  lines.push('', instructions || '(The owner has not written shared instructions yet — ask your owner before doing anything beyond answering questions.)');
+  const knowledge = Array.isArray(ctx.allowed_knowledge) ? ctx.allowed_knowledge : [];
+  if (knowledge.length) {
+    lines.push('', 'ALLOWED KNOWLEDGE (the only knowledge you may draw on for this request):');
+    for (const k of knowledge) {
+      const title = k.title || k.slug || 'untitled';
+      lines.push('', `--- ${title}${k.slug ? ` (@knowledge:${k.slug})` : ''} ---`, (k.content || '').trim() || '(empty)');
+      if (k.truncated) lines.push('[truncated]');
+    }
+  }
+  lines.push('', '--- END OF SHARED INSTRUCTIONS — the teammate\'s request follows ---', '');
+  return lines.join('\n');
+}
+
 // ── Poll-cursor persistence ──
 // An adapter that starts by jumping to the head of the event stream silently
 // drops every message that arrived while it was down (crash, update, user
@@ -60,6 +122,18 @@ const CURSOR_RESUME_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 // heartbeat_failed up to the daemon. A success resets the streak immediately.
 const HEARTBEAT_ERROR_THRESHOLD = 2;
 
+// ── Control-poller deadlines ──
+// The control poller is one chain of awaits, and it is the only thing that
+// delivers Stop. When a link in it never settles — it has: a control poll
+// whose response was cut off mid-body — the agent goes on working and
+// answering while every later control event sits unread until the daemon
+// restarts, and nothing in the log says so. So neither the fetch nor a
+// handler is awaited without a bound. A handler that overruns is not
+// cancelled or re-run; the poller only stops waiting for it.
+const CONTROL_POLL_DEADLINE_MS = 20 * 1000;
+const CONTROL_ACTION_DEADLINE_MS = 60 * 1000;
+const CONTROL_DEADLINE_HIT = Symbol('control deadline hit');
+
 /**
  * Model variables whose name does not follow `<TYPE>_MODEL`. Only the ones an
  * adapter really reads — see `modelLabel`, which tries `<TYPE>_MODEL` first
@@ -104,7 +178,7 @@ class BaseAdapter {
    * @param {string} opts.agentName
    * @param {string} [opts.endpoint]
    */
-  constructor({ workspaceId, channelName, token, agentName, endpoint, agentEnv, agentType, workingDir, onStatus }) {
+  constructor({ workspaceId, channelName, token, agentName, endpoint, agentEnv, agentType, workingDir, onStatus, logSink }) {
     this.workspaceId = workspaceId;
     this.channelName = channelName;
     this.token = token;
@@ -128,7 +202,8 @@ class BaseAdapter {
     // Set when the user explicitly stops this adapter (vs an error/revoke), so a
     // clean stop is never mislabeled as an error.
     this._stopRequested = false;
-    this.client = new WorkspaceClient(this.endpoint);
+    // Acts for this one agent: X-Agent-Name on every request (permission model v1.1).
+    this.client = new WorkspaceClient(this.endpoint, { agentName: this.agentName });
     this._lastEventId = null;
     this._cursorFile = this._cursorFilePath();
     this._lastPersistedCursor = null;
@@ -144,6 +219,8 @@ class BaseAdapter {
     this.workspaceModel = null;
     this._lastControlId = null;
     this._controlWake = null;
+    this._CONTROL_POLL_DEADLINE_MS = CONTROL_POLL_DEADLINE_MS;
+    this._CONTROL_ACTION_DEADLINE_MS = CONTROL_ACTION_DEADLINE_MS;
     // Per-channel task tracking for parallel execution
     this._channelBusy = new Set();
     this._channelQueues = {};
@@ -161,6 +238,7 @@ class BaseAdapter {
     // adapter can tell "a stop landed while I was preparing this turn" from
     // "this turn started after the stop and is meant to run".
     this._channelRunGeneration = {};
+    this._channelRequestContent = {};
     // Channels a user stopped whose next turn has not started yet. Everything
     // the send* helpers would post there is dropped: output a killed run was
     // still flushing lands after the stop notice otherwise, and the workspace
@@ -193,15 +271,33 @@ class BaseAdapter {
     // (Claude) fetch directly instead and leave it false.
     this._usesPinnedContext = false;
     this._pinnedContext = {}; // channel → { decisions, glossary }
+    // ── v1.1 M3/M4 ──
+    // Debounce handle for the busy↔idle presence heartbeat.
+    this._presenceHeartbeatTimer = null;
+    // channel → { fetchedAt, requesterEmail, ctx } from /shared-context.
+    this._sharedContext = {};
+    // channel → email of the person whose message is being handled (so the
+    // per-run MCP server can tell the owner who asked).
+    this._requesterEmail = {};
     // Wall-clock timestamp of adapter init, used by the `status` control
     // action to report uptime back to the channel. Reset on reinstantiation
     // (e.g. after a `restart` IPC bounce) so uptime tracks "time since last
     // restart" rather than the long-running daemon's process uptime.
     this._startedAt = Date.now();
-    this._log = (msg) => {
+    // Inside the daemon, `logSink` routes lines through its daemon.log writer
+    // (batching, repeat suppression, rotation). Standalone, they go to stdout.
+    const sink = typeof logSink === 'function' ? logSink : null;
+    this._log = (msg, level = 'info') => {
+      if (sink) return sink(level, msg);
       const ts = new Date().toISOString();
-      console.log(`${ts} INFO adapter [${this.agentName}]: ${msg}`);
+      console.log(`${ts} ${String(level).toUpperCase()} adapter [${this.agentName}]: ${msg}`);
     };
+    // Runs of identical background failures (see failure-streak.js).
+    this._pollFailures = new FailureStreak();
+    this._heartbeatFailures = new FailureStreak();
+    // The control poller (Stop, mode changes) fails silently otherwise: its
+    // errors are caught so the loop keeps going, and nothing else logs them.
+    this._controlFailures = new FailureStreak();
   }
 
   // ------------------------------------------------------------------
@@ -337,7 +433,7 @@ class BaseAdapter {
         this._log(`Synced model from workspace: ${this.workspaceModel}`);
       }
     } catch (e) {
-      this._log(`Warning: skill sync failed (non-fatal): ${e.message}`);
+      this._log(`Warning: skill sync failed (non-fatal): ${e.message}`, 'warn');
     }
 
     // Fast-path operations (control-event cursor + heartbeat + control poll)
@@ -352,7 +448,7 @@ class BaseAdapter {
     try {
       // Send initial heartbeat
       try { await this._heartbeat(); } catch (e) {
-        this._log(`Heartbeat failed (non-fatal): ${e.message}`);
+        this._log(`Heartbeat failed (non-fatal): ${e.message}`, 'warn');
       }
       // Slow path: only the message-poll loop waits for this.
       await this._skipExistingEvents();
@@ -362,6 +458,7 @@ class BaseAdapter {
       this._running = false;
       this._wakeControlPoller();
       clearInterval(heartbeatInterval);
+      if (this._presenceHeartbeatTimer) { clearTimeout(this._presenceHeartbeatTimer); this._presenceHeartbeatTimer = null; }
       try { await controlPoller; } catch {}
       try {
         await this.client.disconnect(this.workspaceId, this.agentName, this.token);
@@ -412,7 +509,7 @@ class BaseAdapter {
     } catch (e) {
       if (!this._warnedCursorPersist) {
         this._warnedCursorPersist = true;
-        this._log(`Could not persist poll cursor (${e.message}) — a restart will skip messages that arrive while offline`);
+        this._log(`Could not persist poll cursor (${e.message}) — a restart will skip messages that arrive while offline`, 'warn');
       }
     }
   }
@@ -453,14 +550,39 @@ class BaseAdapter {
   // Heartbeat
   // ------------------------------------------------------------------
 
+  /** Presence fields for the next heartbeat (see buildPresenceFields). */
+  presenceFields() {
+    return buildPresenceFields(this._channelBusy, this._channelQueues);
+  }
+
+  /**
+   * A channel just went busy or idle (or its queue changed): send a heartbeat
+   * soon so the roster flips promptly instead of on the next 30s tick. Bursts
+   * collapse into one send.
+   */
+  _schedulePresenceHeartbeat() {
+    if (!this._running) return;
+    if (this._presenceHeartbeatTimer) return;
+    this._presenceHeartbeatTimer = setTimeout(() => {
+      this._presenceHeartbeatTimer = null;
+      if (!this._running) return;
+      this._heartbeat().catch(() => {});
+    }, PRESENCE_HEARTBEAT_DEBOUNCE_MS);
+    if (typeof this._presenceHeartbeatTimer.unref === 'function') this._presenceHeartbeatTimer.unref();
+  }
+
   async _heartbeat() {
     try {
-      await this.client.heartbeat(this.workspaceId, this.agentName, this.token, this._sessionId);
+      await this.client.heartbeat(this.workspaceId, this.agentName, this.token, this._sessionId, this.presenceFields());
       this._heartbeatFailStreak = 0;
+      const recovered = this._heartbeatFailures.succeed();
+      if (recovered) {
+        this._log(`Workspace heartbeat recovered after ${recovered.count} unsuccessful attempt(s) over ${formatDuration(recovered.ms)}`);
+      }
       this._reportStatus(null); // alive → clear any prior connectivity error
     } catch (e) {
       if (e instanceof SessionRevokedError) {
-        this._log(`SESSION REVOKED: another client joined as '${this.agentName}'. Stopping adapter.`);
+        this._log(`SESSION REVOKED: another client joined as '${this.agentName}'. Stopping adapter.`, 'warn');
         // Terminal (not a user stop): record so the daemon can show why it ended.
         this._setExitInfo(REASON.SESSION_REVOKED, 'Workspace session revoked — another client joined with the same agent name');
         this._reportStatus(REASON.SESSION_REVOKED, 'Workspace session revoked');
@@ -471,7 +593,9 @@ class BaseAdapter {
       // single transient blip (or an expected brief reconnect) isn't mislabeled.
       this._heartbeatFailStreak++;
       const { reason, message } = classifyHeartbeatError(e);
-      this._log(`${message} (consecutive failures: ${this._heartbeatFailStreak})`);
+      if (this._heartbeatFailures.fail()) {
+        this._log(`${message} (consecutive failures: ${this._heartbeatFailStreak})`, 'warn');
+      }
       if (this._heartbeatFailStreak >= HEARTBEAT_ERROR_THRESHOLD) {
         this._reportStatus(reason, message);
       }
@@ -504,10 +628,16 @@ class BaseAdapter {
 
   async _pollControl() {
     try {
-      const events = await this.client.pollControl(
-        this.workspaceId, this.agentName, this.token,
-        { after: this._lastControlId }
+      const events = await this._withinControlDeadline(
+        this.client.pollControl(
+          this.workspaceId, this.agentName, this.token,
+          { after: this._lastControlId }
+        ),
+        this._CONTROL_POLL_DEADLINE_MS, 'control poll',
       );
+      // A poll abandoned at its deadline delivered nothing; the cursor has
+      // not moved, so the next one asks for the same events again.
+      if (events === CONTROL_DEADLINE_HIT) return;
       for (const ev of events) {
         if (ev.id) this._lastControlId = ev.id;
         const payload = ev.payload || {};
@@ -523,12 +653,48 @@ class BaseAdapter {
           // Handled here for every adapter, never by an override: a stop has
           // to stay inside the channel it names, and each adapter used to
           // decide that for itself — several stopped every channel.
-          await this._handleUserStop(payload.channel || null);
+          await this._withinControlDeadline(
+            this._handleUserStop(payload.channel || null),
+            this._CONTROL_ACTION_DEADLINE_MS, `stop for ${payload.channel || 'every channel'}`,
+          );
         } else {
-          await this._onControlAction(action, payload);
+          await this._withinControlDeadline(
+            this._onControlAction(action, payload),
+            this._CONTROL_ACTION_DEADLINE_MS, `control action '${action}'`,
+          );
         }
       }
-    } catch {}
+      const recovered = this._controlFailures.succeed();
+      if (recovered) {
+        this._log(`Control poll recovered after ${recovered.count} unsuccessful attempt(s) over ${formatDuration(recovered.ms)}`);
+      }
+    } catch (e) {
+      // Keep polling, but leave a trace: a control channel that keeps failing
+      // means Stop and mode changes are not reaching this agent.
+      if (this._controlFailures.fail()) {
+        const count = this._controlFailures.count;
+        const streak = count > 1 ? ` (consecutive failures: ${count})` : '';
+        this._log(`Control poll failed: ${e && e.message}${streak}`, isTransientNetworkError(e) ? 'warn' : 'error');
+      }
+    }
+  }
+
+  /**
+   * Await `work` for at most `ms`. Resolves to CONTROL_DEADLINE_HIT when the
+   * deadline wins; `work` is left to finish, or not, on its own.
+   */
+  _withinControlDeadline(work, ms, what) {
+    let timer;
+    const deadline = new Promise((resolve) => {
+      timer = setTimeout(() => {
+        this._log(`Control poller: ${what} still pending after ${Math.round(ms / 1000)}s — polling on without it`, 'warn');
+        resolve(CONTROL_DEADLINE_HIT);
+      }, ms);
+    });
+    return Promise.race([
+      Promise.resolve(work).finally(() => clearTimeout(timer)),
+      deadline,
+    ]);
   }
 
   /**
@@ -593,7 +759,7 @@ class BaseAdapter {
     }
     if (!channel) {
       try { await this._stopSharedWork(); } catch (e) {
-        this._log(`Stop: shared work did not stop cleanly: ${e && e.message ? e.message : e}`);
+        this._log(`Stop: shared work did not stop cleanly: ${e && e.message ? e.message : e}`, 'warn');
       }
     }
     for (const ch of channels) {
@@ -601,7 +767,7 @@ class BaseAdapter {
       try {
         outcome = await this._stopChannelWork(ch);
       } catch (e) {
-        this._log(`Stop: ${ch} did not stop cleanly: ${e && e.message ? e.message : e}`);
+        this._log(`Stop: ${ch} did not stop cleanly: ${e && e.message ? e.message : e}`, 'warn');
         outcome = 'failed';
       }
       // The pressed channel is always answered, so its UI settles even when
@@ -788,7 +954,7 @@ class BaseAdapter {
         skillId, state: 'installing',
       });
     } catch (e) {
-      this._log(`skill.install: could not report 'installing' (non-fatal): ${e && e.message ? e.message : e}`);
+      this._log(`skill.install: could not report 'installing' (non-fatal): ${e && e.message ? e.message : e}`, 'warn');
     }
 
     try {
@@ -822,19 +988,19 @@ class BaseAdapter {
           skillId, state: 'installed', path: result.path, partial: result.partial === true,
         });
       } catch (e) {
-        this._log(`skill.install: installed on disk but failed to report 'installed': ${e && e.message ? e.message : e}`);
+        this._log(`skill.install: installed on disk but failed to report 'installed': ${e && e.message ? e.message : e}`, 'warn');
       }
       this._log(`skill.install: SUCCESS "${skillId}" → ${result.path}${result.partial ? ' (partial)' : ''}`);
       await this._onSkillsChanged();
     } catch (e) {
       const msg = e && e.message ? e.message : String(e);
-      this._log(`skill.install: FAILED "${skillId}": ${msg}`);
+      this._log(`skill.install: FAILED "${skillId}": ${msg}`, 'error');
       try {
         await this.client.reportSkillStatus(this.workspaceId, this.agentName, this.token, {
           skillId, state: 'failed', error: msg,
         });
       } catch (e2) {
-        this._log(`skill.install: also failed to report 'failed': ${e2 && e2.message ? e2.message : e2}`);
+        this._log(`skill.install: also failed to report 'failed': ${e2 && e2.message ? e2.message : e2}`, 'warn');
       }
     }
   }
@@ -863,12 +1029,12 @@ class BaseAdapter {
           skillId, state: 'uninstalled',
         });
       } catch (e) {
-        this._log(`skill.uninstall: failed to report status: ${e && e.message ? e.message : e}`);
+        this._log(`skill.uninstall: failed to report status: ${e && e.message ? e.message : e}`, 'warn');
       }
       await this._onSkillsChanged();
     } catch (e) {
       const msg = e && e.message ? e.message : String(e);
-      this._log(`skill.uninstall: FAILED "${skillId}": ${msg}`);
+      this._log(`skill.uninstall: FAILED "${skillId}": ${msg}`, 'error');
     }
   }
 
@@ -923,7 +1089,7 @@ class BaseAdapter {
         sessionId: this._sessionId,
       });
     } catch (e) {
-      this._log(`Status: failed to post: ${e && e.message ? e.message : e}`);
+      this._log(`Status: failed to post: ${e && e.message ? e.message : e}`, 'warn');
     }
   }
 
@@ -950,7 +1116,7 @@ class BaseAdapter {
         (r) => r.created_by === prefixed || r.created_by === this.agentName,
       );
     } catch (e) {
-      this._log(`Routines: failed to list: ${e && e.message ? e.message : e}`);
+      this._log(`Routines: failed to list: ${e && e.message ? e.message : e}`, 'warn');
       try {
         await this.client.sendMessage(
           this.workspaceId, channel, this.token,
@@ -991,7 +1157,7 @@ class BaseAdapter {
         sessionId: this._sessionId,
       });
     } catch (e) {
-      this._log(`Routines: failed to post: ${e && e.message ? e.message : e}`);
+      this._log(`Routines: failed to post: ${e && e.message ? e.message : e}`, 'warn');
     }
   }
 
@@ -1049,11 +1215,26 @@ class BaseAdapter {
         rawCursor = result.cursor;
         composingActive = !!result.composing;
         this._pollAuthFailStreak = 0;
+        const recovered = this._pollFailures.succeed();
+        if (recovered) {
+          this._log(`Poll recovered after ${recovered.count} unsuccessful attempt(s) over ${formatDuration(recovered.ms)}`);
+        }
         if (pollCount <= 3 || pollCount % 20 === 0) {
           this._log(`Poll #${pollCount}: ${messages.length} messages, cursor=${rawCursor || 'none'}${composingActive ? ' composing' : ''}`);
         }
       } catch (e) {
-        this._log(`Poll #${pollCount} failed: ${e.message} \nStack: ${e.stack}`);
+        // A workspace that is down or slow fails every poll until it is back;
+        // log the streak, not every attempt (see failure-streak.js).
+        if (this._pollFailures.fail()) {
+          const count = this._pollFailures.count;
+          const streak = count > 1 ? ` (consecutive failures: ${count})` : '';
+          if (isTransientNetworkError(e)) {
+            this._log(`Poll #${pollCount} failed: ${e.message}${streak} — retrying every 5s`, 'warn');
+          } else {
+            const stack = count === 1 && e && e.stack ? `\nStack: ${e.stack}` : '';
+            this._log(`Poll #${pollCount} failed: ${e && e.message}${streak}${stack}`, 'error');
+          }
+        }
         // A rejected credential never heals by retrying with the same token —
         // it means the device was re-paired/unpaired and this adapter is
         // running on a revoked one. After a few consecutive rejections (not
@@ -1187,6 +1368,7 @@ class BaseAdapter {
       msg._queueId = queueId;
       msg._acceptedGeneration = this._stopGenerationFor(channel);
       this._channelQueues[channel].push(msg);
+      this._schedulePresenceHeartbeat();
       try {
         await this.sendStatus(channel, 'message queued — will process after current task', {
           queued_message: (msg.content || '').slice(0, 200),
@@ -1217,6 +1399,7 @@ class BaseAdapter {
 
   async _channelWorker(channel, msg) {
     this._channelBusy.add(channel);
+    this._schedulePresenceHeartbeat();
     // Messages an adapter queues for itself (Claude's todo nudge) carry no
     // generation; they belong to the turn that queued them.
     const startGeneration = msg._acceptedGeneration !== undefined
@@ -1236,6 +1419,16 @@ class BaseAdapter {
         }
         // Pinned entries may have changed while this message waited.
         await this._prefetchPinnedContext(channel);
+        this._channelRequestContent[channel] = current.originalContent ?? current.content;
+        if (channel && !channel.startsWith('dm:') && current.messageId
+            && typeof this.client?.getRecentMessages === 'function') {
+          await this._applyThreadHistory(channel, current);
+        }
+        // A teammate's request runs under the owner-reviewed shared
+        // instructions (v1.1 M4); the block is prepended to the message.
+        // Gated synchronously so messages it cannot apply to (agents,
+        // anonymous humans, system) add no extra tick before the stop check.
+        if (this._sharedContextCandidate(current)) await this._applySharedContext(channel, current);
         // Checked after the round trips above, which a stop can land inside:
         // a message from before the stop never reaches the CLI.
         if (generation !== this._stopGenerationFor(channel)) {
@@ -1249,10 +1442,11 @@ class BaseAdapter {
           await this._handleMessage(current);
         }
       } catch (e) {
-        this._log(`Error ${first ? 'in channel worker' : 'processing queued message'} for ${channel}: ${e.message}`);
+        this._log(`Error ${first ? 'in channel worker' : 'processing queued message'} for ${channel}: ${e.message}`, 'error');
         try { await this.sendError(channel, `Agent error: ${e.message}`); } catch {}
       }
       delete this._channelRunGeneration[channel];
+      delete this._channelRequestContent[channel];
       first = false;
 
       const queue = this._channelQueues[channel];
@@ -1260,6 +1454,91 @@ class BaseAdapter {
     }
     if (dropped) this._log(`Stop in ${channel} — dropped ${dropped} message(s) accepted before it`);
     this._channelBusy.delete(channel);
+    delete this._requesterEmail[channel];
+    this._schedulePresenceHeartbeat();
+  }
+
+  // ------------------------------------------------------------------
+  // Shared context for teammates' requests (v1.1 M4)
+  // ------------------------------------------------------------------
+
+  /** The email of the person whose request this channel is running, if known. */
+  requesterEmailFor(channel) {
+    return this._requesterEmail[channel] || null;
+  }
+
+  /**
+   * Fetch (cached 60s per channel + requester) the owner-reviewed shared
+   * context for this run. Returns the /shared-context payload or null.
+   */
+  async _fetchSharedContext(channel, requesterEmail) {
+    const cached = this._sharedContext[channel];
+    const now = Date.now();
+    if (cached && cached.requesterEmail === requesterEmail && (now - cached.fetchedAt) < SHARED_CONTEXT_TTL_MS) {
+      return cached.ctx;
+    }
+    if (!this.client || typeof this.client.getSharedContext !== 'function') return null;
+    try {
+      const ctx = await this.client.getSharedContext(this.workspaceId, this.token, this.agentName, {
+        requesterEmail, channel,
+      });
+      this._sharedContext[channel] = { fetchedAt: now, requesterEmail, ctx };
+      return ctx;
+    } catch (e) {
+      this._log(`Shared-context fetch failed (${e && e.message ? e.message : e}) — running without it`);
+      // Keep a stale-but-recent answer rather than flip-flopping on a blip.
+      return cached && cached.requesterEmail === requesterEmail ? cached.ctx : null;
+    }
+  }
+
+  /**
+   * When the triggering message comes from an identified person, look up the
+   * shared context and, if it applies, prepend the instruction block to the
+   * message the adapter will turn into its prompt. Records the requester for
+   * the per-run MCP server. Never throws.
+   */
+  _sharedContextEmail(msg) {
+    if (!msg || msg.senderType !== 'human') return null;
+    const raw = msg.senderEmail || (msg.metadata && msg.metadata.sender_email) || '';
+    const email = String(raw).trim().toLowerCase();
+    return email && email.includes('@') ? email : null;
+  }
+
+  _sharedContextCandidate(msg) {
+    return this._sharedContextEmail(msg) !== null;
+  }
+
+  async _applySharedContext(channel, msg) {
+    const email = this._sharedContextEmail(msg);
+    if (!email) return false;
+    this._requesterEmail[channel] = email;
+    if (msg._sharedContextApplied) return true;
+    const ctx = await this._fetchSharedContext(channel, email);
+    const block = buildSharedContextBlock(ctx);
+    if (!block) return false;
+    if (msg.originalContent === undefined) msg.originalContent = msg.content;
+    msg.content = block + '\n' + (msg.content || '');
+    msg._sharedContextApplied = true;
+    this._log(`Shared context applied for ${email} in ${channel} (owner: ${ctx.owner_email || '?'})`);
+    return true;
+  }
+
+  async _applyThreadHistory(channel, msg) {
+    // DMs have separate peer sessions. Synthetic nudges have no event boundary.
+    if (!channel || channel.startsWith('dm:') || !msg.messageId || msg._threadHistoryApplied) return;
+    if (typeof this.client?.getRecentMessages !== 'function') return;
+    try {
+      const messages = await this.client.getRecentMessages(this.workspaceId, channel, this.token, 100, {
+        before: msg.messageId, timeout: 5000, throwOnError: true,
+      });
+      const block = buildThreadHistory(messages, channel, msg);
+      if (!block) return;
+      if (msg.originalContent === undefined) msg.originalContent = msg.content;
+      msg.content = block + (msg.content || '');
+      msg._threadHistoryApplied = true;
+    } catch (e) {
+      this._log(`Recent thread history unavailable for ${channel}: ${e.message}`);
+    }
   }
 
   // ------------------------------------------------------------------
@@ -1333,7 +1612,7 @@ class BaseAdapter {
           delete cache[channel];
           // Entry is gone — fall through to list+match below.
         } else {
-          this._log(`${label} read failed (${e.message}) — reusing last known state`);
+          this._log(`${label} read failed (${e.message}) — reusing last known state`, 'warn');
           return { available: true, state: 'found', entryId: cachedId, title: titles[0], content: null, error: true };
         }
       }
@@ -1369,7 +1648,7 @@ class BaseAdapter {
       }
       return { available: true, state: 'found', entryId: entry.id, title: matchedTitle, content: (full && full.content) || '', error: false };
     } catch (e) {
-      this._log(`${label} fetch failed (${e.message}) — reusing last known state`);
+      this._log(`${label} fetch failed (${e.message}) — reusing last known state`, 'warn');
       const knownId = cache[channel] || null;
       return { available: true, state: knownId ? 'found' : 'unknown', entryId: knownId, title: knownId ? titles[0] : null, content: null, error: true };
     }
@@ -1427,7 +1706,7 @@ class BaseAdapter {
       }
       this._pinnedContext[channel] = fresh;
     } catch (e) {
-      this._log(`Pinned-context fetch failed (${e && e.message ? e.message : e}) — reusing the last pinned context`);
+      this._log(`Pinned-context fetch failed (${e && e.message ? e.message : e}) — reusing the last pinned context`, 'warn');
     }
   }
 
@@ -1463,7 +1742,7 @@ class BaseAdapter {
   async _autoTitleChannel(channel, content) {
     if (this._titledSessions.has(channel)) return;
     this._titledSessions.add(channel);
-    const title = generateSessionTitle(content);
+    const title = generateSessionTitle(this._channelRequestContent[channel] ?? content);
     if (!title) return;
     try {
       const info = await this.client.getSession(this.workspaceId, channel, this.token);
@@ -1475,7 +1754,7 @@ class BaseAdapter {
         this._log(`Auto-titled channel: ${title}`);
       }
     } catch (e) {
-      this._log(`Failed to auto-title channel: ${e.message}`);
+      this._log(`Failed to auto-title channel: ${e.message}`, 'warn');
     }
   }
 
@@ -1529,7 +1808,21 @@ class BaseAdapter {
   async sendResponse(channel, content) {
     if (this._isMuted(channel)) return;
     try {
+      let attachments = [];
+      if (!(this.disabledModules || new Set()).has('files') && channel && !channel.startsWith('dm:') && this.client.uploadFile) {
+        const published = await publishResponseArtifacts({
+          content,
+          workingDir: this.workingDir,
+          upload: (filename, bytes, contentType) => this.client.uploadFile(this.workspaceId, this.token, filename, bytes, {
+            contentType, source: `openagents:${this.agentName}`, channelName: channel, visibility: 'inherit',
+          }),
+          onError: () => this._log('Could not attach a linked document; leaving its original link in the reply.'),
+        });
+        content = published.content;
+        attachments = published.attachments;
+      }
       await this.client.sendMessage(this.workspaceId, channel, this.token, content, {
+        attachments,
         senderType: 'agent',
         senderName: this.agentName,
         metadata: { status_kind: 'completed' },
@@ -1625,7 +1918,7 @@ class BaseAdapter {
   }
 
   _onSessionRevoked() {
-    this._log(`SESSION REVOKED: another client joined as '${this.agentName}'. Stopping adapter.`);
+    this._log(`SESSION REVOKED: another client joined as '${this.agentName}'. Stopping adapter.`, 'warn');
     this._running = false;
   }
 
@@ -1672,3 +1965,7 @@ class BaseAdapter {
 module.exports = BaseAdapter;
 module.exports.STALE_MESSAGE_MAX_AGE_MS = STALE_MESSAGE_MAX_AGE_MS;
 module.exports.CURSOR_RESUME_MAX_AGE_MS = CURSOR_RESUME_MAX_AGE_MS;
+module.exports.PRESENCE_HEARTBEAT_DEBOUNCE_MS = PRESENCE_HEARTBEAT_DEBOUNCE_MS;
+module.exports.SHARED_CONTEXT_TTL_MS = SHARED_CONTEXT_TTL_MS;
+module.exports.buildPresenceFields = buildPresenceFields;
+module.exports.buildSharedContextBlock = buildSharedContextBlock;