@openagents-org/agent-launcher 0.2.192 → 0.2.194

package/src/workspace-client.js

@@ -5,6 +5,29 @@ const http = require('http');
 
 const DEFAULT_ENDPOINT = 'https://workspace-endpoint.openagents.org';
 
+/**
+ * The error a request deadline produces. Every request carries a hard
+ * AbortSignal.timeout deadline (see _get), and when it fires Node rejects with
+ * a bare "AbortError: The operation was aborted" — which reads like somebody
+ * cancelled the call and names no cause. The socket-inactivity timeout said
+ * "Request timed out". Both now say the same thing, with the deadline, and
+ * carry ETIMEDOUT so callers can tell a slow network from a bug.
+ */
+function requestTimeoutError(timeout) {
+  const after = timeout >= 1000 ? `${Math.round(timeout / 1000)}s` : `${timeout}ms`;
+  const err = new Error(`Request timed out after ${after}`);
+  err.code = 'ETIMEDOUT';
+  return err;
+}
+
+/** A request 'error' handler that reports a fired deadline as a timeout. */
+function rejectWithDeadline(reject, timeout) {
+  return (err) => {
+    const aborted = err && (err.name === 'AbortError' || err.code === 'ABORT_ERR');
+    reject(aborted ? requestTimeoutError(timeout) : err);
+  };
+}
+
 /**
  * Thrown when the workspace rejects a request because our session_id has
  * been revoked by a newer /v1/join as the same agent. Callers should
@@ -18,6 +41,30 @@ class SessionRevokedError extends Error {
   }
 }
 
+/**
+ * Reject when a response is cut off after its headers arrived.
+ *
+ * Node reports that on the RESPONSE, and nowhere else: once a response
+ * exists the request emits no 'error' for a connection that closes early,
+ * 'end' only fires for a complete body, and the request's abort signal is a
+ * no-op by then because the socket is already gone. A request helper that
+ * listens for 'end' alone therefore never settles — and each poll loop is a
+ * single await, so one truncated response (a backend restart mid-reply is
+ * enough) silences that loop for the life of the daemon. When it is the
+ * control poller the agent keeps working and answering, and ignores Stop.
+ */
+function rejectOnTruncatedResponse(res, reject) {
+  res.on('error', reject);
+  res.on('close', () => {
+    if (res.complete) return;
+    // Same code Node puts on the 'error' above, so callers count either as
+    // the network blip it is.
+    const err = new Error('Response ended before it was complete');
+    err.code = 'ECONNRESET';
+    reject(err);
+  });
+}
+
 /**
  * HTTP client for workspace API operations.
  *
@@ -25,8 +72,34 @@ class SessionRevokedError extends Error {
  * auth headers (X-Workspace-Token), same request/response shapes.
  */
 class WorkspaceClient {
-  constructor(endpoint) {
+  /**
+   * @param {string} [endpoint]
+   * @param {{ agentName?: string }} [opts] — when the client acts for ONE
+   *   agent, pass its name: every request then carries `X-Agent-Name` so the
+   *   workspace can apply that agent's permissions (permission model v1.1 §3)
+   *   instead of treating the call as an anonymous machine. Machine-level
+   *   clients (daemon device heartbeat, pairing redeem, workspace removal)
+   *   pass nothing and send no agent identity.
+   */
+  constructor(endpoint, { agentName } = {}) {
     this.endpoint = (endpoint || DEFAULT_ENDPOINT).replace(/\/$/, '');
+    this.agentName = typeof agentName === 'string' && agentName.trim() ? agentName.trim() : null;
+  }
+
+  /** A client for the same endpoint that acts as `agentName` (or none). */
+  withAgent(agentName) {
+    return new WorkspaceClient(this.endpoint, { agentName });
+  }
+
+  /**
+   * Request headers + the agent identity header. Applied in every transport
+   * helper (_get/_getRaw/_post/_put/_patch/_delete) so no call site can forget
+   * it. Returns a copy — callers' header objects are never mutated.
+   */
+  _withAgent(headers) {
+    const out = { ...(headers || {}) };
+    if (this.agentName && !out['X-Agent-Name']) out['X-Agent-Name'] = this.agentName;
+    return out;
   }
 
   /**
@@ -194,16 +267,80 @@ class WorkspaceClient {
    *   If the server's current session for this agent differs, _post()
    *   throws SessionRevokedError and the caller should stop its adapter.
    */
-  async heartbeat(workspaceId, agentName, token, sessionId) {
+  async heartbeat(workspaceId, agentName, token, sessionId, presence) {
     const body = {
       agent_name: agentName,
       network: workspaceId,
     };
     if (sessionId) body.session_id = sessionId;
+    // v1.1 M3 — busy/queued detail ({ presence_state, busy_channels,
+    // queue_depth }, see BaseAdapter.buildPresenceFields). Optional so older
+    // callers keep sending the legacy body.
+    if (presence && typeof presence === 'object') {
+      if (presence.presence_state !== undefined) body.presence_state = presence.presence_state;
+      if (Array.isArray(presence.busy_channels)) body.busy_channels = presence.busy_channels;
+      if (Number.isFinite(presence.queue_depth)) body.queue_depth = presence.queue_depth;
+    }
     const data = await this._post('/v1/heartbeat', body, this._wsHeaders(token));
     return data.data || data;
   }
 
+  // ── Agent profile / presence (v1.1 M3/M4) ────────────────────────────────
+
+  /** GET /v1/agents/{agent}/availability → { status, presence_state,
+   * busy_channels, queue_depth, runtime_status, runtime_name, reason }. */
+  async getAgentAvailability(workspaceId, token, agentName) {
+    const data = await this._get(
+      `/v1/agents/${encodeURIComponent(agentName)}/availability?network=${encodeURIComponent(workspaceId)}`,
+      this._wsHeaders(token),
+    );
+    return data.data || data;
+  }
+
+  /** GET /v1/agents/{agent}/profile — the specialist card. */
+  async getAgentProfile(workspaceId, token, agentName) {
+    const data = await this._get(
+      `/v1/agents/${encodeURIComponent(agentName)}/profile?network=${encodeURIComponent(workspaceId)}`,
+      this._wsHeaders(token),
+    );
+    return data.data || data;
+  }
+
+  /**
+   * GET /v1/agents/{agent}/shared-context — what THIS agent's run may use when
+   * the request comes from a teammate rather than its owner. Machine-only.
+   * Returns { apply, owner_email, requester_email, shared_instructions,
+   * allowed_knowledge: [{ slug, title, content }], cost_owner }.
+   */
+  async getSharedContext(workspaceId, token, agentName, { requesterEmail, channel, timeout } = {}) {
+    const params = new URLSearchParams({ network: workspaceId });
+    if (requesterEmail) params.set('requester_email', requesterEmail);
+    if (channel) params.set('channel', channel);
+    const data = await this._get(
+      `/v1/agents/${encodeURIComponent(agentName)}/shared-context?${params}`,
+      this._wsHeaders(token),
+      timeout || 5000,
+    );
+    return data.data || data;
+  }
+
+  /**
+   * Raw message events of a channel (newest first by default) — for callers
+   * that need payload/metadata fields _eventToMessage drops (e.g. hand-offs).
+   */
+  async getChannelEvents(workspaceId, channelName, token, { limit = 100, sort = 'desc' } = {}) {
+    const params = new URLSearchParams({
+      network: workspaceId,
+      channel: channelName,
+      type: 'workspace.message',
+      sort,
+      limit: String(Math.min(Math.max(1, limit), 500)),
+    });
+    const data = await this._get(`/v1/events?${params}`, this._wsHeaders(token));
+    const result = data.data || data;
+    return (result && result.events) || [];
+  }
+
   /**
    * Disconnect agent via POST /v1/leave. Best-effort (ignores errors).
    */
@@ -300,7 +437,7 @@ class WorkspaceClient {
    * previous session fails (the channel's chat history is the only thing
    * that survives a session-storage rotation).
    */
-  async getRecentMessages(workspaceId, channelName, token, limit = 30, { sort = 'desc' } = {}) {
+  async getRecentMessages(workspaceId, channelName, token, limit = 30, { sort = 'desc', before, timeout, throwOnError = false } = {}) {
     try {
       const params = new URLSearchParams({
         network: workspaceId,
@@ -309,14 +446,16 @@ class WorkspaceClient {
         sort,
         limit: String(limit),
       });
-      const data = await this._get(`/v1/events?${params}`, this._wsHeaders(token));
+      if (before) params.set('before', before);
+      const data = await this._get(`/v1/events?${params}`, this._wsHeaders(token), timeout);
       const result = data.data || data;
       const events = (result && result.events) || [];
       // A desc window arrives newest-first; reverse so the caller always gets
       // chronological order. An asc window is already chronological.
       const ordered = sort === 'asc' ? events.slice() : events.slice().reverse();
       return ordered.map((e) => this._eventToMessage(e));
-    } catch {
+    } catch (error) {
+      if (throwOnError) throw error;
       return [];
     }
   }
@@ -564,8 +703,17 @@ class WorkspaceClient {
   /**
    * Upload a file via POST /v1/files/base64.
    */
+  async publishWebProject(workspaceId, token, project, projectId) {
+    const body = { ...project, network: workspaceId };
+    const route = '/v1/web-projects' + (projectId ? '/' + encodeURIComponent(projectId) : '');
+    const data = projectId
+      ? await this._put(route, body, this._wsHeaders(token), 60000)
+      : await this._post(route, body, this._wsHeaders(token), 60000);
+    return data.data || data;
+  }
+
   async uploadFile(workspaceId, token, filename, contentBase64, {
-    contentType = 'application/octet-stream', source = 'human:user', channelName,
+    contentType = 'application/octet-stream', source = 'human:user', channelName, visibility,
   } = {}) {
     const body = {
       filename,
@@ -575,6 +723,7 @@ class WorkspaceClient {
       source,
     };
     if (channelName) body.channel_name = channelName;
+    if (visibility) body.visibility = visibility;
 
     const data = await this._post('/v1/files/base64', body, this._wsHeaders(token), 60000);
     return data.data || data;
@@ -652,8 +801,8 @@ class WorkspaceClient {
   /**
    * Open a new browser tab via POST /v1/browser/tabs.
    */
-  async browserOpenTab(workspaceId, token, { url = 'about:blank', source = 'human:user', context_id } = {}) {
-    const body = { url, network: workspaceId, source };
+  async browserOpenTab(workspaceId, token, { url = 'about:blank', source = 'human:user', context_id, channel } = {}) {
+    const body = { url, network: workspaceId, source, channel };
     if (context_id) body.context_id = context_id;
     const data = await this._post('/v1/browser/tabs', body, this._wsHeaders(token));
     return data.data || data;
@@ -671,24 +820,24 @@ class WorkspaceClient {
   /**
    * Navigate a browser tab via POST /v1/browser/tabs/{tabId}/navigate.
    */
-  async browserNavigate(workspaceId, token, tabId, url) {
-    const data = await this._post(`/v1/browser/tabs/${tabId}/navigate`, { url }, this._wsHeaders(token));
+  async browserNavigate(workspaceId, token, tabId, url, { source, channel } = {}) {
+    const data = await this._post(`/v1/browser/tabs/${tabId}/navigate`, { url, source, channel }, this._wsHeaders(token));
     return data.data || data;
   }
 
   /**
    * Click an element via POST /v1/browser/tabs/{tabId}/click.
    */
-  async browserClick(workspaceId, token, tabId, selector) {
-    const data = await this._post(`/v1/browser/tabs/${tabId}/click`, { selector }, this._wsHeaders(token));
+  async browserClick(workspaceId, token, tabId, selector, { source, channel } = {}) {
+    const data = await this._post(`/v1/browser/tabs/${tabId}/click`, { selector, source, channel }, this._wsHeaders(token));
     return data.data || data;
   }
 
   /**
    * Type text via POST /v1/browser/tabs/{tabId}/type.
    */
-  async browserType(workspaceId, token, tabId, selector, text) {
-    const data = await this._post(`/v1/browser/tabs/${tabId}/type`, { selector, text }, this._wsHeaders(token));
+  async browserType(workspaceId, token, tabId, selector, text, { source, channel } = {}) {
+    const data = await this._post(`/v1/browser/tabs/${tabId}/type`, { selector, text, source, channel }, this._wsHeaders(token));
     return data.data || data;
   }
 
@@ -696,16 +845,22 @@ class WorkspaceClient {
    * Get screenshot via GET /v1/browser/tabs/{tabId}/screenshot.
    * @returns {Buffer}
    */
-  async browserScreenshot(workspaceId, token, tabId) {
-    return this._getRaw(`/v1/browser/tabs/${tabId}/screenshot`, this._wsHeaders(token), 30000);
+  async browserScreenshot(workspaceId, token, tabId, { source, channel } = {}) {
+    const query = new URLSearchParams();
+    if (source) query.set('source', source);
+    if (channel) query.set('channel', channel);
+    return this._getRaw(`/v1/browser/tabs/${tabId}/screenshot?${query}`, this._wsHeaders(token), 30000);
   }
 
   /**
    * Get accessibility snapshot via GET /v1/browser/tabs/{tabId}/snapshot.
    * @returns {string}
    */
-  async browserSnapshot(workspaceId, token, tabId) {
-    const buf = await this._getRaw(`/v1/browser/tabs/${tabId}/snapshot`, this._wsHeaders(token));
+  async browserSnapshot(workspaceId, token, tabId, { source, channel } = {}) {
+    const query = new URLSearchParams();
+    if (source) query.set('source', source);
+    if (channel) query.set('channel', channel);
+    const buf = await this._getRaw(`/v1/browser/tabs/${tabId}/snapshot?${query}`, this._wsHeaders(token));
     return buf.toString('utf-8');
   }
 
@@ -920,11 +1075,25 @@ class WorkspaceClient {
       sessionId,
       senderType: isHuman ? 'human' : 'agent',
       senderName,
+      senderDisplayName: payload.sender_display_name || (event.metadata || {}).sender_display_name || null,
       content: (payload.content || event.content || ''),
       mentions: payload.mentions || [],
       messageType: payload.message_type || 'chat',
       metadata: event.metadata || {},
     };
+    // The person behind a human message (v1.1): mobile puts it in the
+    // payload, the Launcher in metadata, the web app uses its email as the
+    // sender id. Used to fetch the owner-reviewed shared context for a
+    // teammate's request and to tell the owner who asked.
+    if (isHuman) {
+      const meta = event.metadata || {};
+      const email = [payload.sender_email, meta.sender_email, payload.sender_id]
+        .find((v) => typeof v === 'string' && /^[^\s@]+@[^\s@]+$/.test(v.trim()));
+      if (email) msg.senderEmail = email.trim().toLowerCase();
+    }
+    if (payload.handoff && typeof payload.handoff === 'object') {
+      msg.handoff = payload.handoff;
+    }
     if (ts) {
       msg.createdAt = new Date(ts).toISOString();
     }
@@ -934,6 +1103,60 @@ class WorkspaceClient {
     return msg;
   }
 
+  // ── Approvals ─────────────────────────────────────────────────────────────
+
+  /** File an approval request (POST /v1/approvals). Returns the record; its
+   * `status` may already be approved/rejected when policy auto-decided. */
+  async createApproval(workspaceId, token, {
+    channel, kind, action, details, risk, source, assignee_email, requester_email,
+  } = {}) {
+    const body = {
+      network: workspaceId,
+      channel,
+      kind: kind || 'other',
+      action,
+      source: source || 'openagents:unknown',
+    };
+    if (details) body.details = String(details).slice(0, 4000);
+    if (risk) body.risk = risk;
+    if (assignee_email) body.assignee_email = assignee_email;
+    if (requester_email) body.requester_email = requester_email;
+    const data = await this._post('/v1/approvals', body, this._wsHeaders(token));
+    return data.data || data;
+  }
+
+  async getApproval(workspaceId, token, approvalId) {
+    const params = new URLSearchParams({ network: workspaceId });
+    const data = await this._get(`/v1/approvals/${encodeURIComponent(approvalId)}?${params}`, this._wsHeaders(token));
+    return data.data || data;
+  }
+
+  // ── Work brief (v1.1 M5) ──────────────────────────────────────────────────
+
+  /** Read a thread's shared work brief (GET /v1/channels/{channel}/brief).
+   * Empty fields come back null / [] when nothing has been written yet. */
+  async getBrief(workspaceId, token, channelName) {
+    const params = new URLSearchParams({ network: workspaceId });
+    const data = await this._get(
+      `/v1/channels/${encodeURIComponent(channelName)}/brief?${params}`,
+      this._wsHeaders(token),
+    );
+    return data.data || data;
+  }
+
+  /** Partial upsert of a thread's brief (PUT /v1/channels/{channel}/brief).
+   * Only the keys present in `fields` change; `source` is recorded as the
+   * writer ("openagents:<agent>"). */
+  async putBrief(workspaceId, token, channelName, fields = {}, { source } = {}) {
+    const body = { network: workspaceId, source: source || 'openagents:unknown', ...fields };
+    const data = await this._put(
+      `/v1/channels/${encodeURIComponent(channelName)}/brief`,
+      body,
+      this._wsHeaders(token),
+    );
+    return data.data || data;
+  }
+
   _wsHeaders(token) {
     return {
       'Content-Type': 'application/json',
@@ -942,6 +1165,7 @@ class WorkspaceClient {
   }
 
   _get(urlPath, headers = {}, timeout = 15000) {
+    headers = this._withAgent(headers);
     const fullUrl = this.endpoint + urlPath;
 
     return new Promise((resolve, reject) => {
@@ -962,28 +1186,37 @@ class WorkspaceClient {
         signal: AbortSignal.timeout(timeout),
       }, (res) => {
         let data = '';
+        rejectOnTruncatedResponse(res, reject);
         res.on('data', (chunk) => { data += chunk; });
         res.on('end', () => {
           try {
             const parsed = JSON.parse(data);
             if (res.statusCode >= 400) {
-              reject(new Error(parsed.message || `HTTP ${res.statusCode}`));
+              const err = new Error(parsed.message || `HTTP ${res.statusCode}`);
+              // Lets the poll loop tell a rejected credential (401/403) and an
+              // overloaded server (5xx) apart from a bug.
+              err.status = res.statusCode;
+              reject(err);
             } else {
               resolve(parsed);
             }
           } catch {
-            reject(new Error(`Invalid response: ${data.slice(0, 200)}`));
+            // A proxy's HTML error page (502/504) lands here.
+            const err = new Error(`Invalid response: ${data.slice(0, 200)}`);
+            if (res.statusCode >= 400) err.status = res.statusCode;
+            reject(err);
           }
         });
       });
 
-      req.on('error', reject);
-      req.on('timeout', () => { req.destroy(); reject(new Error('Request timed out')); });
+      req.on('error', rejectWithDeadline(reject, timeout));
+      req.on('timeout', () => { req.destroy(); reject(requestTimeoutError(timeout)); });
       req.end();
     });
   }
 
   _getRaw(urlPath, headers = {}, timeout = 15000) {
+    headers = this._withAgent(headers);
     const fullUrl = this.endpoint + urlPath;
 
     return new Promise((resolve, reject) => {
@@ -997,6 +1230,7 @@ class WorkspaceClient {
         signal: AbortSignal.timeout(timeout), // hard deadline (covers DNS/connect); see _get
       }, (res) => {
         const chunks = [];
+        rejectOnTruncatedResponse(res, reject);
         res.on('data', (chunk) => { chunks.push(chunk); });
         res.on('end', () => {
           const buf = Buffer.concat(chunks);
@@ -1008,13 +1242,14 @@ class WorkspaceClient {
         });
       });
 
-      req.on('error', reject);
-      req.on('timeout', () => { req.destroy(); reject(new Error('Request timed out')); });
+      req.on('error', rejectWithDeadline(reject, timeout));
+      req.on('timeout', () => { req.destroy(); reject(requestTimeoutError(timeout)); });
       req.end();
     });
   }
 
   _post(urlPath, body, headers = {}, timeout = 30000) {
+    headers = this._withAgent(headers);
     if (!headers['Content-Type']) headers['Content-Type'] = 'application/json';
     const jsonBody = JSON.stringify(body);
     const fullUrl = this.endpoint + urlPath;
@@ -1030,6 +1265,7 @@ class WorkspaceClient {
         signal: AbortSignal.timeout(timeout), // hard deadline (covers DNS/connect); see _get
       }, (res) => {
         let data = '';
+        rejectOnTruncatedResponse(res, reject);
         res.on('data', (chunk) => { data += chunk; });
         res.on('end', () => {
           try {
@@ -1058,14 +1294,15 @@ class WorkspaceClient {
         });
       });
 
-      req.on('error', reject);
-      req.on('timeout', () => { req.destroy(); reject(new Error('Request timed out')); });
+      req.on('error', rejectWithDeadline(reject, timeout));
+      req.on('timeout', () => { req.destroy(); reject(requestTimeoutError(timeout)); });
       req.write(jsonBody);
       req.end();
     });
   }
 
   _put(urlPath, body, headers = {}, timeout = 30000) {
+    headers = this._withAgent(headers);
     if (!headers['Content-Type']) headers['Content-Type'] = 'application/json';
     const jsonBody = JSON.stringify(body);
     const fullUrl = this.endpoint + urlPath;
@@ -1081,6 +1318,7 @@ class WorkspaceClient {
         signal: AbortSignal.timeout(timeout), // hard deadline (covers DNS/connect); see _get
       }, (res) => {
         let data = '';
+        rejectOnTruncatedResponse(res, reject);
         res.on('data', (chunk) => { data += chunk; });
         res.on('end', () => {
           try {
@@ -1101,14 +1339,15 @@ class WorkspaceClient {
         });
       });
 
-      req.on('error', reject);
-      req.on('timeout', () => { req.destroy(); reject(new Error('Request timed out')); });
+      req.on('error', rejectWithDeadline(reject, timeout));
+      req.on('timeout', () => { req.destroy(); reject(requestTimeoutError(timeout)); });
       req.write(jsonBody);
       req.end();
     });
   }
 
   _patch(urlPath, body, headers = {}, timeout = 15000) {
+    headers = this._withAgent(headers);
     if (!headers['Content-Type']) headers['Content-Type'] = 'application/json';
     const jsonBody = JSON.stringify(body);
     const fullUrl = this.endpoint + urlPath;
@@ -1124,6 +1363,7 @@ class WorkspaceClient {
         signal: AbortSignal.timeout(timeout), // hard deadline (covers DNS/connect); see _get
       }, (res) => {
         let data = '';
+        rejectOnTruncatedResponse(res, reject);
         res.on('data', (chunk) => { data += chunk; });
         res.on('end', () => {
           try {
@@ -1139,14 +1379,15 @@ class WorkspaceClient {
         });
       });
 
-      req.on('error', reject);
-      req.on('timeout', () => { req.destroy(); reject(new Error('Request timed out')); });
+      req.on('error', rejectWithDeadline(reject, timeout));
+      req.on('timeout', () => { req.destroy(); reject(requestTimeoutError(timeout)); });
       req.write(jsonBody);
       req.end();
     });
   }
 
   _delete(urlPath, headers = {}, network) {
+    headers = this._withAgent(headers);
     const fullUrl = this.endpoint + urlPath + (network ? `?network=${network}` : '');
 
     return new Promise((resolve, reject) => {
@@ -1160,6 +1401,7 @@ class WorkspaceClient {
         signal: AbortSignal.timeout(15000), // hard deadline (covers DNS/connect); see _get
       }, (res) => {
         let data = '';
+        rejectOnTruncatedResponse(res, reject);
         res.on('data', (chunk) => { data += chunk; });
         res.on('end', () => {
           try {
@@ -1175,8 +1417,8 @@ class WorkspaceClient {
         });
       });
 
-      req.on('error', reject);
-      req.on('timeout', () => { req.destroy(); reject(new Error('Request timed out')); });
+      req.on('error', rejectWithDeadline(reject, 15000));
+      req.on('timeout', () => { req.destroy(); reject(requestTimeoutError(15000)); });
       req.end();
     });
   }