@openagents-org/agent-launcher 0.2.192 → 0.2.194

package/src/postinstall-stub.js

@@ -0,0 +1,69 @@
+'use strict';
+
+/**
+ * The placeholder an npm package ships where its native binary goes.
+ *
+ * opencode-ai and @anthropic-ai/claude-code are both published this way: the
+ * package's `bin` (bin/opencode.exe, bin/claude.exe) is a few hundred bytes of
+ * shell that prints "postinstall … not run" and exits 1, and the package's
+ * postinstall script swaps in the real binary from a per-platform optional
+ * dependency. Skip that script — `ignore-scripts=true` in an npmrc,
+ * `--ignore-scripts`, pnpm and bun by default — and the install still exits 0
+ * with the placeholder sitting where the CLI should be. It resolves on PATH
+ * and it has the right name, so nothing about it looks like a missing install:
+ * the launcher reports the agent installed, and every run fails on whatever
+ * check happens to come next.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// A native CLI is tens of megabytes; the placeholders are about 500 bytes.
+const STUB_MAX_BYTES = 4096;
+const STUB_SIGNATURE = /postinstall (script )?(was|did) not run|native binary not installed/i;
+
+/** Whether text a CLI printed is its package's placeholder talking. */
+function isPostinstallStubOutput(text) {
+  return STUB_SIGNATURE.test(String(text || ''));
+}
+
+function isStubFile(file) {
+  try {
+    const st = fs.statSync(file);
+    if (!st.isFile() || st.size > STUB_MAX_BYTES) return false;
+    return STUB_SIGNATURE.test(fs.readFileSync(file, 'utf-8'));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The files an npm `.cmd` shim launches. The shim is a wrapper npm wrote
+ * beside the package, never the placeholder itself — the placeholder is what
+ * it points at (`"%dp0%\node_modules\opencode-ai\bin\opencode.exe" %*`).
+ */
+function cmdShimTargets(file) {
+  if (!/\.cmd$/i.test(file)) return [];
+  try {
+    if (fs.statSync(file).size > STUB_MAX_BYTES) return [];
+    const dir = path.dirname(file);
+    const text = fs.readFileSync(file, 'utf-8');
+    return [...text.matchAll(/"%(?:~dp0|dp0%)\\?([^"\r\n]+)"/g)]
+      .map((m) => path.join(dir, ...m[1].split(/[\\/]+/)));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Whether `file` is such a placeholder — directly, through the symlink npm
+ * puts in `.bin`, or through a Windows `.cmd` shim. Read off disk rather than
+ * by running it: on Windows the placeholder is shell text named `.exe`, and
+ * starting it raises a "this app can't run on your PC" dialog.
+ */
+function isPostinstallStub(file) {
+  if (!file) return false;
+  return [file, ...cmdShimTargets(file)].some(isStubFile);
+}
+
+module.exports = { isPostinstallStub, isPostinstallStubOutput };

package/src/tools-v11/brief.js

@@ -0,0 +1,97 @@
+'use strict';
+/**
+ * v1.1 M5 — the shared work brief.
+ *
+ * Every thread has one brief (objective, owner, latest result, open
+ * questions, next step) that people read instead of scrolling the
+ * transcript. Agents keep it current after each meaningful step.
+ *
+ *   workspace_get_brief    { channel? }
+ *   workspace_update_brief { objective?, latest_result?, open_questions?, next_step?, owner? }
+ *
+ * Only the fields passed to update are changed; the backend records the
+ * writer as `openagents:<agent>`.
+ */
+
+const defs = [
+  {
+    name: 'workspace_get_brief',
+    description:
+      'Read the shared work brief of a thread: objective, owner of the next step, latest result, ' +
+      'open questions and next step, plus who directs the thread (director_email). Defaults to the current thread.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        channel: { type: 'string', description: 'Thread id (default: the current thread)' },
+      },
+    },
+  },
+  {
+    name: 'workspace_update_brief',
+    description:
+      'Update the current thread\'s shared work brief. Pass only the fields that changed. ' +
+      'Call it after each meaningful step so people can see where the work stands without reading the transcript.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        objective: { type: 'string', description: 'What this thread is trying to achieve (one or two sentences)' },
+        latest_result: { type: 'string', description: 'The most recent concrete outcome (what was produced / verified)' },
+        open_questions: { type: 'array', items: { type: 'string' }, description: 'Questions blocking or shaping the work. Replaces the list.' },
+        next_step: { type: 'string', description: 'The very next action' },
+        owner: { type: 'string', description: 'Who owns the next step: "openagents:<agent>" or "human:<email>"' },
+      },
+    },
+  },
+];
+
+const FIELDS = ['objective', 'latest_result', 'open_questions', 'next_step', 'owner'];
+
+function renderBrief(b) {
+  if (!b) return 'No brief yet.';
+  const lines = [`Brief for ${b.channel || 'this thread'}:`];
+  if (b.director_email) lines.push(`Directed by: ${b.director_email}`);
+  lines.push(`Objective: ${b.objective || '—'}`);
+  lines.push(`Owner of next step: ${b.owner || '—'}`);
+  lines.push(`Latest result: ${b.latest_result || '—'}`);
+  const qs = Array.isArray(b.open_questions) ? b.open_questions : [];
+  lines.push(qs.length ? `Open questions:\n${qs.map((q) => `  - ${q}`).join('\n')}` : 'Open questions: —');
+  lines.push(`Next step: ${b.next_step || '—'}`);
+  if (b.updated_by) lines.push(`Updated by ${b.updated_by}${b.updated_at ? ` at ${b.updated_at}` : ''}`);
+  return lines.join('\n');
+}
+
+async function handle(server, name, args, helpers) {
+  const { text } = helpers;
+  args = args || {};
+
+  if (name === 'workspace_get_brief') {
+    const channel = (args.channel && String(args.channel).trim()) || server.channelName;
+    if (!channel) return text('No thread in scope — pass `channel`.');
+    const brief = await server.ws.getBrief(server.workspaceId, server.token, channel);
+    return text(renderBrief(brief));
+  }
+
+  if (name === 'workspace_update_brief') {
+    if (!server.channelName) return text('No thread in scope — the brief belongs to a thread.');
+    const fields = {};
+    for (const k of FIELDS) {
+      if (args[k] === undefined) continue;
+      if (k === 'open_questions') {
+        fields[k] = Array.isArray(args[k]) ? args[k].map((q) => String(q)) : [];
+      } else {
+        fields[k] = args[k] === null ? null : String(args[k]);
+      }
+    }
+    if (Object.keys(fields).length === 0) {
+      return text('Nothing to update — pass at least one of: ' + FIELDS.join(', ') + '.');
+    }
+    const brief = await server.ws.putBrief(server.workspaceId, server.token, server.channelName, fields, {
+      source: `openagents:${server.agentName}`,
+    });
+    return text(`Brief updated (${Object.keys(fields).join(', ')}).\n${renderBrief(brief)}`);
+  }
+
+  return undefined;
+}
+
+module.exports = { defs, handle };

package/src/tools-v11/index.js

@@ -0,0 +1,28 @@
+'use strict';
+/**
+ * Roadmap v1.1 workspace tools — one module per milestone so parallel work
+ * never edits the same file. Each module exports:
+ *   defs   : MCP tool definitions (array)
+ *   handle : async (server, name, args, helpers) => result | undefined
+ * `server` is the McpServer instance (ws, workspaceId, channelName,
+ * agentName, token, _log); `helpers` is { text, image }.
+ */
+const modules = [
+  require('./presence-handoff'),  // M3/M6 — presence detail + structured hand-off
+  require('./brief'),             // M5 — shared work brief
+];
+
+function toolDefs() {
+  return modules.flatMap((m) => m.defs || []);
+}
+
+async function dispatch(server, name, args, helpers) {
+  for (const m of modules) {
+    if (!m.handle) continue;
+    const r = await m.handle(server, name, args, helpers);
+    if (r !== undefined) return r;
+  }
+  return undefined;
+}
+
+module.exports = { toolDefs, dispatch };

package/src/tools-v11/presence-handoff.js

@@ -0,0 +1,199 @@
+'use strict';
+/**
+ * Roadmap v1.1 M3/M6 — presence detail + structured agent-to-agent hand-off.
+ *
+ *   workspace_agent_availability  is <agent> free / busy / offline / runtime down?
+ *   workspace_handoff             hand work to another agent with request, context,
+ *                                 output so far and next owner travelling together
+ *   workspace_get_handoffs        the recent hand-offs in a thread
+ *
+ * A hand-off is an ordinary `workspace.message.posted` chat message that
+ * OPENS with `@<to_agent>` (the backend's deterministic explicit-target path:
+ * it routes to exactly that agent and adds it to the thread) and carries the
+ * structured record twice — `payload.handoff` for readers of the thread and
+ * `metadata.handoff` for routing/analytics — so nothing depends on parsing
+ * the markdown back out.
+ */
+
+const MAX_HANDOFFS = 10;
+
+const defs = [
+  {
+    name: 'workspace_agent_availability',
+    description:
+      'Check whether another agent can take work right now. Returns its status, whether it is busy ' +
+      '(and in which threads / how many messages are queued), whether the device it runs on is ' +
+      'online, and one reason: available | busy | agent_offline | runtime_offline.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        agent: { type: 'string', description: 'Agent name (without the openagents: prefix)' },
+      },
+      required: ['agent'],
+    },
+  },
+  {
+    name: 'workspace_handoff',
+    description:
+      'Hand a piece of work to another agent in the current thread. Posts "@<to_agent> <request>" with ' +
+      'optional Context / Output so far / Next owner sections so the request, what it needs, what you ' +
+      'already produced and who owns the next step travel together. Only the addressed agent is woken. ' +
+      'Use workspace_agent_availability first if timing matters.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        to_agent: { type: 'string', description: 'Agent to hand the work to (name only)' },
+        request: { type: 'string', description: 'What you are asking the agent to do — one or two sentences' },
+        context: { type: 'string', description: 'Background the agent needs (inputs, constraints, links, file ids)' },
+        output: { type: 'string', description: 'What you have already produced (results, paths, partial work)' },
+        next_owner: { type: 'string', description: 'Who owns the next step after this (defaults to to_agent)' },
+      },
+      required: ['to_agent', 'request'],
+    },
+  },
+  {
+    name: 'workspace_get_handoffs',
+    description:
+      'List the most recent structured hand-offs in a thread (newest first, max 10): who handed what to ' +
+      'whom, with the context, output and next owner they carried. Defaults to the current thread.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        channel: { type: 'string', description: 'Thread name; omit for the current one' },
+        limit: { type: 'integer', description: 'How many to return (1-10, default 10)' },
+      },
+    },
+  },
+];
+
+function cleanName(name) {
+  return String(name || '').trim().replace(/^@/, '').replace(/^openagents:/, '');
+}
+
+function cleanText(v, max) {
+  if (v === undefined || v === null) return null;
+  const s = String(v).trim();
+  if (!s) return null;
+  return max && s.length > max ? s.slice(0, max) + '…' : s;
+}
+
+/**
+ * Build the hand-off record + message content. Pure; exported for tests.
+ * Returns { handoff, content } where handoff =
+ *   { from, to, request, context, output, next_owner }.
+ */
+function buildHandoff(from, { to_agent, request, context, output, next_owner } = {}) {
+  const to = cleanName(to_agent);
+  const req = cleanText(request, 4000);
+  if (!to) throw new Error('to_agent is required');
+  if (!req) throw new Error('request is required');
+  const handoff = {
+    from: cleanName(from),
+    to,
+    request: req,
+    context: cleanText(context, 8000),
+    output: cleanText(output, 8000),
+    next_owner: cleanName(next_owner) || to,
+  };
+  let content = `@${to} ${req}`;
+  if (handoff.context) content += `\n\nContext:\n${handoff.context}`;
+  if (handoff.output) content += `\n\nOutput so far:\n${handoff.output}`;
+  content += `\n\nNext owner: ${handoff.next_owner}`;
+  return { handoff, content };
+}
+
+/** The hand-off records found in a list of raw events (newest first). */
+function extractHandoffs(events, limit = MAX_HANDOFFS) {
+  const out = [];
+  for (const e of events || []) {
+    const payload = e.payload || {};
+    const meta = e.metadata || {};
+    const h = (payload.handoff && typeof payload.handoff === 'object') ? payload.handoff
+      : (meta.handoff && typeof meta.handoff === 'object') ? meta.handoff : null;
+    if (!h) continue;
+    out.push({
+      id: e.id || null,
+      timestamp: e.timestamp || null,
+      from: h.from || String(e.source || '').replace(/^openagents:/, ''),
+      to: h.to || null,
+      request: h.request || null,
+      context: h.context || null,
+      output: h.output || null,
+      next_owner: h.next_owner || h.to || null,
+    });
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
+function describeAvailability(agent, a) {
+  const bits = [`${agent}: ${a.reason || 'unknown'}`];
+  bits.push(`status=${a.status || '?'}`);
+  if (a.presence_state) bits.push(`presence=${a.presence_state}`);
+  if (Array.isArray(a.busy_channels) && a.busy_channels.length) bits.push(`busy in: ${a.busy_channels.join(', ')}`);
+  if (a.queue_depth) bits.push(`queued: ${a.queue_depth}`);
+  if (a.runtime_status) bits.push(`runtime ${a.runtime_status}${a.runtime_name ? ` (${a.runtime_name})` : ''}`);
+  const hint = {
+    available: 'It can take work now.',
+    busy: 'It will answer after the current run — a hand-off is queued, not lost.',
+    agent_offline: 'Its connector is not running; a message will wait until it reconnects.',
+    runtime_offline: 'The device it runs on is offline; nobody will pick this up until it is back.',
+  }[a.reason];
+  return bits.join(' · ') + (hint ? `\n${hint}` : '');
+}
+
+async function handle(server, name, args, helpers) {
+  const { text } = helpers;
+  args = args || {};
+  switch (name) {
+    case 'workspace_agent_availability': {
+      const agent = cleanName(args.agent);
+      if (!agent) throw new Error('agent is required');
+      const a = await server.ws.getAgentAvailability(server.workspaceId, server.token, agent);
+      return text(describeAvailability(agent, a || {}));
+    }
+
+    case 'workspace_handoff': {
+      const { handoff, content } = buildHandoff(server.agentName, args);
+      if (handoff.to === handoff.from) throw new Error('You cannot hand work to yourself');
+      const event = {
+        type: 'workspace.message.posted',
+        source: `openagents:${server.agentName}`,
+        target: `channel/${server.channelName}`,
+        payload: { content, message_type: 'chat', handoff },
+        metadata: { handoff, explicit_targets: [handoff.to] },
+      };
+      if (server.requesterEmail) event.metadata.requester_email = server.requesterEmail;
+      const result = await server.ws.sendEvent(server.workspaceId, event, server.token);
+      const targets = (result && result.metadata && result.metadata.target_agents) || [];
+      const delivered = targets.includes(handoff.to);
+      return text(
+        `Handed off to @${handoff.to}${delivered ? '' : ' (warning: the workspace did not route it — is that agent in this workspace?)'}. ` +
+        `Next owner: ${handoff.next_owner}. End your turn now unless you have other work; ` +
+        `@${handoff.to} will reply in this thread.`,
+      );
+    }
+
+    case 'workspace_get_handoffs': {
+      const channel = args.channel || server.channelName;
+      const limit = Math.min(Math.max(1, parseInt(args.limit, 10) || MAX_HANDOFFS), MAX_HANDOFFS);
+      const events = await server.ws.getChannelEvents(server.workspaceId, channel, server.token, { limit: 200, sort: 'desc' });
+      const handoffs = extractHandoffs(events, limit);
+      if (!handoffs.length) return text(`No hand-offs in ${channel} yet.`);
+      const lines = handoffs.map((h, i) => {
+        const parts = [`${i + 1}. ${h.from || '?'} → ${h.to || '?'}: ${h.request || ''}`];
+        if (h.context) parts.push(`   Context: ${h.context}`);
+        if (h.output) parts.push(`   Output so far: ${h.output}`);
+        if (h.next_owner) parts.push(`   Next owner: ${h.next_owner}`);
+        if (h.timestamp) parts.push(`   at ${new Date(h.timestamp).toISOString()}`);
+        return parts.join('\n');
+      });
+      return text(`Hand-offs in ${channel} (newest first):\n${lines.join('\n')}`);
+    }
+
+    default:
+      return undefined;
+  }
+}
+
+module.exports = { defs, handle, buildHandoff, extractHandoffs };