@shipers-dev/multi 0.18.0 → 0.20.1

package/README.md

@@ -0,0 +1,47 @@
+# @shipers-dev/multi
+
+CLI daemon (`multi-agent`) that pairs a device with a Multi workspace and runs assigned issues via ACP / acpx adapters.
+
+## Install
+
+```bash
+bun add -g @shipers-dev/multi
+# or
+npm i -g @shipers-dev/multi
+```
+
+## Quick start
+
+```bash
+multi-agent setup            # pair the device against prod
+multi-agent start            # foreground daemon
+multi-agent start -d         # detached
+multi-agent status
+multi-agent logs
+```
+
+## Pointing at a local API worker
+
+For local development against a wrangler-dev API worker, set `MULTI_API` to its base URL:
+
+```bash
+MULTI_API=http://localhost:8787 multi-agent setup
+MULTI_API=http://localhost:8787 multi-agent start
+```
+
+The resolved API base URL is printed at start. When the host is `localhost` / `127.0.0.1` / `[::1]`, the daemon:
+
+- skips spawning `cloudflared` (no quick-tunnel),
+- advertises `http://127.0.0.1:<port>` as its push endpoint, so the local worker can reach the daemon directly over loopback,
+- skips the tunnel self-heal + DNS probe loops.
+
+`MULTI_API_URL` is still accepted as a fallback alias. CLI flag `--api <url>` overrides both.
+
+## Common env vars
+
+| Var | Purpose |
+| --- | --- |
+| `MULTI_API` | API base URL (default `https://multi-api.adnb3r.workers.dev`) |
+| `MULTI_MAX_CONCURRENT` | Max concurrent tasks per device (default 3) |
+| `MULTI_TUNNEL_NAME` | Use a named cloudflared tunnel instead of quick tunnel |
+| `MULTI_TUNNEL_HOSTNAME` | Public hostname routed to the named tunnel |

package/dist/index.js

@@ -16071,6 +16071,83 @@ var StreamEventInputSchema = exports_external.object({
   event_type: StreamEventTypeSchema,
   payload: exports_external.unknown().optional()
 });
+// ../lib/memory.ts
+var MEMORY_ENTRY_KINDS = ["fact", "event", "instruction", "task"];
+var MemoryEntryKindSchema = exports_external.enum(MEMORY_ENTRY_KINDS);
+var MemoryEntrySchema = exports_external.object({
+  id: exports_external.string(),
+  project_id: exports_external.string(),
+  issue_id: exports_external.string().nullable().optional(),
+  kind: MemoryEntryKindSchema,
+  text: exports_external.string(),
+  source_event_id: exports_external.string().nullable().optional(),
+  source_comment_id: exports_external.string().nullable().optional(),
+  score: exports_external.number().optional(),
+  created_at: exports_external.number()
+});
+var MemoryCitationSchema = exports_external.object({
+  entry_id: exports_external.string(),
+  kind: MemoryEntryKindSchema,
+  issue_id: exports_external.string().nullable().optional(),
+  comment_id: exports_external.string().nullable().optional(),
+  snippet: exports_external.string(),
+  score: exports_external.number().optional()
+});
+var MemoryRecallRequestSchema = exports_external.object({
+  project_id: exports_external.string().min(1),
+  issue_id: exports_external.string().optional(),
+  query: exports_external.string().min(1),
+  k: exports_external.number().int().min(1).max(50).optional()
+});
+var MemoryRecallResponseSchema = exports_external.object({
+  synthesis: exports_external.string(),
+  citations: exports_external.array(MemoryCitationSchema),
+  entries: exports_external.array(MemoryEntrySchema)
+});
+var StreamSourceKind = exports_external.enum(["assistant_text", "result"]);
+var IngestBase = exports_external.object({
+  project_id: exports_external.string().min(1),
+  issue_id: exports_external.string().min(1),
+  ts: exports_external.number().int()
+});
+var MemoryIngestAssistantTextSchema = IngestBase.extend({
+  kind: exports_external.literal("assistant_text"),
+  event_id: exports_external.string(),
+  text: exports_external.string(),
+  final: exports_external.literal(true)
+});
+var MemoryIngestResultSchema = IngestBase.extend({
+  kind: exports_external.literal("result"),
+  event_id: exports_external.string(),
+  text: exports_external.string(),
+  status: exports_external.enum(["success", "error", "stopped"]).optional()
+});
+var MemoryIngestHumanCommentSchema = IngestBase.extend({
+  kind: exports_external.literal("human_comment"),
+  comment_id: exports_external.string(),
+  author_id: exports_external.string(),
+  body: exports_external.string()
+});
+var MemoryIngestIssueChangedSchema = IngestBase.extend({
+  kind: exports_external.literal("issue_changed"),
+  field: exports_external.enum(["title", "description"]),
+  before: exports_external.string().nullable(),
+  after: exports_external.string().nullable(),
+  actor_id: exports_external.string()
+});
+var MemoryIngestEventSchema = exports_external.discriminatedUnion("kind", [
+  MemoryIngestAssistantTextSchema,
+  MemoryIngestResultSchema,
+  MemoryIngestHumanCommentSchema,
+  MemoryIngestIssueChangedSchema
+]);
+var MemoryIngestRequestSchema = exports_external.object({
+  events: exports_external.array(MemoryIngestEventSchema).min(1).max(100)
+});
+var MemoryIngestResponseSchema = exports_external.object({
+  accepted: exports_external.number().int().nonnegative(),
+  rejected: exports_external.number().int().nonnegative()
+});
 // src/worktree.ts
 import { spawn } from "child_process";
 import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, symlinkSync, rmSync } from "fs";
@@ -16426,7 +16503,7 @@ import { join as join5, dirname as dirname4 } from "path";
 // package.json
 var package_default = {
   name: "@shipers-dev/multi",
-  version: "0.18.0",
+  version: "0.20.1",
   type: "module",
   bin: {
     "multi-agent": "./dist/index.js"
@@ -16440,8 +16517,9 @@ var package_default = {
     prepublishOnly: "bun run build"
   },
   dependencies: {
+    "@agentclientprotocol/claude-agent-acp": "^0.31.0",
     "@agentclientprotocol/sdk": "^0.20.0",
-    "@agentclientprotocol/claude-agent-acp": "^0.31.0"
+    effect: "^3.21.2"
   },
   devDependencies: {
     "@multi/lib": "workspace:*"
@@ -16476,6 +16554,14 @@ function ensureDirs() {
       mkdirSync4(d, { recursive: true });
   }
 }
+function isLocalApi(url2) {
+  try {
+    const h = new URL(url2).hostname;
+    return h === "localhost" || h === "127.0.0.1" || h === "0.0.0.0" || h === "[::1]" || h === "::1";
+  } catch {
+    return false;
+  }
+}
 function log(msg) {
   ensureDirs();
   const line = `[${new Date().toISOString()}] ${msg}
@@ -16512,7 +16598,7 @@ async function main() {
     printHelp();
     process.exit(0);
   }
-  const apiUrl = args.values.api || process.env.MULTI_API_URL || "https://multi-api.adnb3r.workers.dev";
+  const apiUrl = args.values.api || process.env.MULTI_API || process.env.MULTI_API_URL || "https://multi-api.adnb3r.workers.dev";
   const config2 = loadConfig();
   if (config2.token)
     setAuthToken(config2.token);
@@ -16700,12 +16786,15 @@ async function cmdConnect(apiUrl, config2) {
   if (existsSync4(STOP_PATH))
     unlinkSync(STOP_PATH);
   const detected = await detectAgents();
+  const localMode = isLocalApi(apiUrl);
   log(`\uD83D\uDE80 Starting daemon for device ${config2.deviceId} (pid ${process.pid})`);
+  log(`   API: ${apiUrl}${localMode ? " (local \u2014 cloudflared skipped)" : ""}`);
   log(`   runtimes: ${detected.map((d) => d.type).join(", ") || "stub"}`);
   const db = openTasksDb();
   db.run("UPDATE tasks SET status = 'queued' WHERE status = 'running'");
   const MAX_DEVICE = Math.max(1, parseInt(process.env.MULTI_MAX_CONCURRENT ?? "3", 10) || 3);
   const running = new Map;
+  let triggerHeartbeat = () => {};
   function resolvePayloadIds(row) {
     let agent_id = row.agent_id;
     let issue_id = row.issue_id;
@@ -16748,6 +16837,7 @@ async function cmdConnect(apiUrl, config2) {
       db.run("UPDATE tasks SET status = 'running', started_at = unixepoch(), attempts = attempts + 1 WHERE id = ?", [row.id]);
       const entry = { agentId: ids.agent_id || "", issueId: ids.issue_id, startedAt: Date.now(), child: null, worktreePath: "" };
       running.set(row.id, entry);
+      triggerHeartbeat();
       (async () => {
         try {
           const task = JSON.parse(row.payload);
@@ -16758,6 +16848,7 @@ async function cmdConnect(apiUrl, config2) {
           db.run("UPDATE tasks SET status = 'failed', finished_at = unixepoch(), error = ? WHERE id = ?", [String(e), row.id]);
         } finally {
           running.delete(row.id);
+          triggerHeartbeat();
           queueMicrotask(() => schedule());
         }
       })();
@@ -16786,7 +16877,7 @@ async function cmdConnect(apiUrl, config2) {
               postStream(apiUrl, t.issue_id, "queued", { queue_position: pos });
             }
             if (t.dispatch_id) {
-              ackDispatch(apiUrl, t.dispatch_id, config2.dispatchSecret);
+              ackDispatch(apiUrl, t.dispatch_id, config2.token);
             }
             queueMicrotask(() => schedule());
             return Response.json({ accepted: true, task_id: taskId }, { status: 202 });
@@ -16881,17 +16972,28 @@ async function cmdConnect(apiUrl, config2) {
   try {
     writeFileSync4(PORT_PATH, String(port));
   } catch {}
-  let tunnel = await startTunnel(port, log);
-  if (!tunnel) {
-    log("\u274C cloudflared did not emit a tunnel URL \u2014 is `cloudflared` installed? (`brew install cloudflared`)");
-    try {
-      server.stop();
-    } catch {}
-    process.exit(1);
+  let tunnel = null;
+  if (localMode) {
+    tunnel = { child: null, url: `http://127.0.0.1:${port}` };
+    log(`\uD83C\uDFE0 Local tunnel: ${tunnel.url}`);
+  } else {
+    tunnel = await startTunnel(port, log);
+    if (!tunnel) {
+      log("\u274C cloudflared did not emit a tunnel URL \u2014 is `cloudflared` installed? (`brew install cloudflared`)");
+      try {
+        server.stop();
+      } catch {}
+      process.exit(1);
+    }
+    log(`\u2601\uFE0F  Tunnel up: ${tunnel.url}`);
   }
-  log(`\u2601\uFE0F  Tunnel up: ${tunnel.url}`);
   const heartbeat = async () => {
-    const res = await apiClient.post(`${apiUrl}/api/devices/${config2.deviceId}/heartbeat`, { status: "online", tunnel_url: tunnel?.url });
+    const res = await apiClient.post(`${apiUrl}/api/devices/${config2.deviceId}/heartbeat`, {
+      status: "online",
+      tunnel_url: tunnel?.url,
+      running_count: running.size,
+      max_concurrent: MAX_DEVICE
+    });
     if (res.success && res.data) {
       const remoteRev = Number(res.data.agent_skill_revision ?? 0);
       if (remoteRev > 0 && remoteRev !== lastMaterializedRevision()) {
@@ -16904,12 +17006,21 @@ async function cmdConnect(apiUrl, config2) {
     }
     return res.success && res.data?.pending_dispatches || 0;
   };
+  let beatTimer = null;
+  triggerHeartbeat = () => {
+    if (beatTimer)
+      return;
+    beatTimer = setTimeout(() => {
+      beatTimer = null;
+      heartbeat().catch(() => {});
+    }, 200);
+  };
   {
     const pending = await heartbeat();
     if (pending > 0)
-      drainOfflineDispatches(apiUrl, config2.deviceId, config2.dispatchSecret, db, () => schedule());
+      drainOfflineDispatches(apiUrl, config2.deviceId, config2.token, db, () => schedule());
   }
-  drainOfflineDispatches(apiUrl, config2.deviceId, config2.dispatchSecret, db, () => schedule());
+  drainOfflineDispatches(apiUrl, config2.deviceId, config2.token, db, () => schedule());
   let alive = true;
   const shutdown = async (reason) => {
     if (!alive)
@@ -16940,7 +17051,7 @@ async function cmdConnect(apiUrl, config2) {
   schedule();
   let restarting = false;
   const restartTunnel = async (reason) => {
-    if (!alive || restarting)
+    if (!alive || restarting || localMode)
       return;
     restarting = true;
     try {
@@ -16958,7 +17069,7 @@ async function cmdConnect(apiUrl, config2) {
           try {
             const pending = await heartbeat();
             if (pending > 0)
-              drainOfflineDispatches(apiUrl, config2.deviceId, config2.dispatchSecret, db, () => schedule());
+              drainOfflineDispatches(apiUrl, config2.deviceId, config2.token, db, () => schedule());
           } catch (e) {
             log(`heartbeat error after tunnel restart: ${String(e)}`);
           }
@@ -16972,20 +17083,21 @@ async function cmdConnect(apiUrl, config2) {
       restarting = false;
     }
   };
-  (async () => {
-    while (alive) {
-      const t = tunnel;
-      if (!t) {
-        await sleep(1000);
-        continue;
+  if (!localMode)
+    (async () => {
+      while (alive) {
+        const t = tunnel;
+        if (!t || !t.child) {
+          await sleep(1000);
+          continue;
+        }
+        const code = await t.child.exited;
+        if (!alive)
+          return;
+        if (tunnel === t)
+          await restartTunnel(`cloudflared exited code=${code}`);
       }
-      const code = await t.child.exited;
-      if (!alive)
-        return;
-      if (tunnel === t)
-        await restartTunnel(`cloudflared exited code=${code}`);
-    }
-  })();
+    })();
   let probeFailures = 0;
   let tick = 0;
   const PROBE_EVERY = 6;
@@ -16997,7 +17109,7 @@ async function cmdConnect(apiUrl, config2) {
     }
     tick++;
     const currentUrl = tunnel?.url;
-    if (currentUrl && tick % PROBE_EVERY === 0) {
+    if (!localMode && currentUrl && tick % PROBE_EVERY === 0) {
       const ok = await probeTunnel(currentUrl);
       if (!ok) {
         probeFailures++;
@@ -17014,7 +17126,7 @@ async function cmdConnect(apiUrl, config2) {
     try {
       const pending = await heartbeat();
       if (pending > 0)
-        drainOfflineDispatches(apiUrl, config2.deviceId, config2.dispatchSecret, db, () => schedule());
+        drainOfflineDispatches(apiUrl, config2.deviceId, config2.token, db, () => schedule());
     } catch (e) {
       log(`heartbeat error: ${String(e)}`);
     }
@@ -17518,6 +17630,7 @@ ${body}
       } catch (e) {
         log(`preamble fetch failed: ${String(e)}`);
       }
+      preamble += await fetchMemoryPreamble(apiUrl, task);
       preamble += await buildPlanningPreamble(apiUrl, task);
       const prompt = preamble ? `${preamble}
 ---
@@ -17583,6 +17696,7 @@ ${body}
           }
         }
       } catch {}
+      preamble += await fetchMemoryPreamble(apiUrl, task);
       preamble += await buildPlanningPreamble(apiUrl, task);
       const issueContext = `## Issue ${task.key}: ${task.title}${task.description ? `
 
@@ -17643,7 +17757,7 @@ ${userPart}` : userPart;
         await eventHandler(event);
     }
     if (liveCommentId) {
-      const n = await uploadOutputDir(apiUrl, liveCommentId, outDir);
+      const n = await uploadOutputDir(apiUrl, liveCommentId, outDir, task.issue_id);
       if (n > 0)
         log(`  \uD83D\uDCCE uploaded ${n} output file(s)`);
     }
@@ -17692,6 +17806,53 @@ ${userPart}` : userPart;
     }
   }
 }
+async function fetchMemoryPreamble(apiUrl, task) {
+  if (process.env.MULTI_MEMORY_ENABLED !== "1")
+    return "";
+  try {
+    const issueRes = await apiClient.get(`${apiUrl}/api/issues/${task.issue_id}`);
+    const projectId = issueRes.data?.project_id;
+    if (!projectId)
+      return "";
+    const title = String(task.title || "").trim();
+    const desc = String(task.description || "").trim();
+    const followup = String(task.followup || "").trim();
+    const query = [title, desc, followup].filter(Boolean).join(`
+`).slice(0, 4000);
+    if (!query)
+      return "";
+    const res = await apiClient.post(`${apiUrl}/api/memory/recall`, {
+      project_id: projectId,
+      issue_id: task.issue_id,
+      query,
+      k: 10
+    });
+    if (!res.success)
+      return "";
+    const synthesis = String(res.data?.synthesis || "").trim();
+    if (!synthesis)
+      return "";
+    const cites = Array.isArray(res.data?.citations) ? res.data.citations : [];
+    let block = `## Project memory
+
+${synthesis}
+`;
+    if (cites.length) {
+      block += `
+`;
+      for (let i = 0;i < cites.length; i++) {
+        const c = cites[i];
+        block += `[${i + 1}] ${String(c.snippet || "").replace(/\s+/g, " ").trim()}
+`;
+      }
+    }
+    return `${block}
+`;
+  } catch (e) {
+    log(`memory recall failed: ${String(e?.message || e)}`);
+    return "";
+  }
+}
 async function buildPlanningPreamble(apiUrl, task) {
   const depth = typeof task.planning_depth === "number" ? task.planning_depth : 0;
   if (depth >= PLANNING_DEPTH_LIMIT) {
@@ -18058,7 +18219,7 @@ function authTokenHeader() {
   const cfg = loadConfig();
   return cfg.token ? `Bearer ${cfg.token}` : null;
 }
-async function uploadOutputDir(apiUrl, commentId, dir) {
+async function uploadOutputDir(apiUrl, commentId, dir, issueId) {
   if (!existsSync4(dir))
     return 0;
   const files = [];
@@ -18087,10 +18248,15 @@ async function uploadOutputDir(apiUrl, commentId, dir) {
       const form = new FormData;
       const blob = new Blob([data]);
       form.append("file", blob, f.split("/").pop() || "file");
+      const headers = {};
+      if (token)
+        headers.Authorization = token;
+      if (issueId)
+        headers["x-issue-id"] = issueId;
       const res = await fetch(`${apiUrl}/api/attachments/comments/${commentId}`, {
         method: "POST",
         body: form,
-        headers: token ? { Authorization: token } : {}
+        headers
       });
       if (res.ok) {
         uploaded++;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipers-dev/multi",
-  "version": "0.18.0",
+  "version": "0.20.1",
   "type": "module",
   "bin": {
     "multi-agent": "./dist/index.js"
@@ -14,8 +14,9 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
+    "@agentclientprotocol/claude-agent-acp": "^0.31.0",
     "@agentclientprotocol/sdk": "^0.20.0",
-    "@agentclientprotocol/claude-agent-acp": "^0.31.0"
+    "effect": "^3.21.2"
   },
   "devDependencies": {
     "@multi/lib": "workspace:*"