@opticell/workflow-companion 1.5.1 → 1.6.0

package/LICENSE

@@ -1,10 +1,21 @@
-WorkFlow Companion
-Copyright (c) 2026 Opticell Limited. All rights reserved.
+MIT License
 
-You may install and run this software free of charge to use WorkFlow for Mac,
-which you must own, from other computers. You may not sell it, or distribute
-modified copies of it.
+Copyright (c) 2026 Opticell Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED. IN NO EVENT SHALL OPTICELL LIMITED BE LIABLE FOR ANY CLAIM, DAMAGES OR
-OTHER LIABILITY ARISING FROM THE SOFTWARE OR ITS USE.
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -133,8 +133,11 @@ npx -y @opticell/workflow-companion wake-on
   shows later in `workflow_state`.
 - **Reads come from a snapshot.** WorkFlow publishes it a few seconds after each
   change, so a read straight after a write can lag slightly.
-- **Files don't travel yet.** Attaching a file, or adding a new version of a
-  document, has to be done in WorkFlow itself.
+- **Files go through your iCloud (1.6).** Attaching a file, filing a document
+  into a project or adding a new version uploads the file to your own iCloud;
+  WorkFlow 5.3 or later on the answering Mac or iPhone attaches it and then
+  deletes the uploaded copy. Up to 50 MB a file. An older WorkFlow ignores the
+  upload and reports the file as missing.
 - **The token is a password.** `~/.workflow-companion/token.txt` opens your
   WorkFlow data in iCloud. Apple replaces it on every request, and the
   companion saves each replacement at once. Several Claude sessions on one

package/index.js

@@ -27,7 +27,7 @@ const path = require("path");
 const os = require("os");
 
 const PROTOCOL_VERSION = "2024-11-05";
-const SERVER_INFO = { name: "workflow", version: "1.5.1" };
+const SERVER_INFO = { name: "workflow", version: "1.6.0" };
 // Who the agent is in WorkFlow: the assignee its queue follows, the @name
 // that calls it, the signature on what it writes. On the Mac it's Claude.
 // A companion goes by the name chosen at setup (default "Companion"), so a
@@ -438,7 +438,45 @@ const cloud = (() => {
     return { status: "pending", message: `Sent to iCloud, but WorkFlow hasn't answered within ${Math.round(schedule.reduce((a, b) => a + b) / 1000)} s (${macLine()}). The command waits safely in iCloud and runs when WorkFlow next looks; its receipt shows in workflow_state.` };
   }
 
-  return { call, lookup, load, send, macLine, pending, takeLate, collect, field };
+  // Files (1.6). The file goes up as its own record of the snapshot's type,
+  // whose "snapshot" asset field is already in the Production schema, so no
+  // schema change was needed. The device that applies the command fetches it
+  // by name and deletes it afterwards. CloudKit Web Services takes an asset
+  // in three steps: ask for an upload address, send the bytes there, then
+  // save a record that refers to what came back.
+  async function upload(file) {
+    const recordName = `upload-${Date.now()}-${Math.random().toString(16).slice(2, 10)}`;
+    const asked = await call("private/assets/upload", { zoneID, tokens: [{ recordType: "BridgeSnapshot", fieldName: "snapshot", recordName }] });
+    const url = asked.tokens && asked.tokens[0] && asked.tokens[0].url;
+    if (!url) throw new Error("iCloud didn't give an address to upload the file to.");
+    let res;
+    try {
+      res = await fetch(url, { method: "POST", headers: { "Content-Type": "application/octet-stream" }, body: fs.readFileSync(file) });
+    } catch (e) {
+      throw new Error(`Couldn't upload ${path.basename(file)} to iCloud (${(e.cause && e.cause.code) || e.message}).`);
+    }
+    if (!res.ok) throw new Error(`iCloud refused the upload of ${path.basename(file)} (HTTP ${res.status}).`);
+    const body = await res.json().catch(() => ({}));
+    if (!body.singleFile) throw new Error("iCloud took the file but didn't say where it is.");
+    const out = await call("private/records/modify", { zoneID, operations: [{ operationType: "create", record: {
+      recordType: "BridgeSnapshot", recordName,
+      fields: {
+        snapshot: { value: body.singleFile },
+        sha: { value: path.basename(file), type: "STRING" },
+        generatedAt: { value: Date.now(), type: "TIMESTAMP" },
+      },
+    } }] });
+    const err = recordError((out.records || [])[0]);
+    if (err) throw err;
+    return recordName;
+  }
+
+  async function discardUpload(recordName) {
+    if (!/^upload-/.test(recordName)) return;
+    await call("private/records/modify", { zoneID, operations: [{ operationType: "forceDelete", record: { recordName } }] });
+  }
+
+  return { call, lookup, load, send, macLine, pending, takeLate, collect, field, upload, discardUpload };
 })();
 
 // The companions WorkFlow knows, from the hidden task the applying device
@@ -507,14 +545,43 @@ function documentLine(d) {
   return `${d.number} v${d.version}  ${d.name}${d.type ? `  [${d.type}]` : ""}${d.status ? `  (${d.status})` : ""}  — ${where}${d.folder ? ` / ${d.folder}` : ""}`;
 }
 
-function stageFile(file) {
-  if (CLOUD) throw new Error("Files can't be sent through iCloud yet — attach it in WorkFlow itself, or put its text in a comment or note.");
-  const src = path.resolve(file.replace(/^~/, os.homedir()));
-  if (!fs.existsSync(src)) throw new Error(`no such file: ${src}`);
+// WorkFlow's own limit on one attachment (PMAttachment.maxAttachmentBytes).
+const MAX_FILE_BYTES = 50 * 1024 * 1024;
+
+// Gets a file to WorkFlow. On the Mac it is copied into the bridge folder;
+// from a companion (1.6) it is uploaded to the user's iCloud first and the
+// command names the upload. Returns the fields the command needs.
+async function stageFile(file) {
+  const src = path.resolve(String(file).replace(/^~/, os.homedir()));
+  if (!fs.existsSync(src) || !fs.statSync(src).isFile()) throw new Error(`no such file: ${src}`);
+  const fileName = path.basename(src);
+  if (CLOUD) {
+    const size = fs.statSync(src).size;
+    if (size > MAX_FILE_BYTES) throw new Error(`${fileName} is ${(size / 1048576).toFixed(1)} MB; WorkFlow takes files up to 50 MB.`);
+    return { fileName, upload: await cloud.upload(src) };
+  }
   fs.mkdirSync(P.attachments, { recursive: true });
-  const staged = path.join(P.attachments, path.basename(src));
+  const staged = path.join(P.attachments, fileName);
   if (path.resolve(staged) !== src) fs.copyFileSync(src, staged);
-  return path.basename(src);
+  return { fileName };
+}
+
+// Sends a file command. If the command never reaches iCloud, the upload it
+// named is removed again rather than left behind.
+async function sendWithFile(op, fields, staged, waitMs) {
+  try {
+    const receipt = await send(op, Object.assign({}, fields, { fileName: staged.fileName, upload: staged.upload }), waitMs);
+    // WorkFlow 5.3+ deletes the upload itself. One that refused the command
+    // (or an older WorkFlow, which doesn't know uploads) leaves it, so it
+    // goes here. Still pending: leave it, the command will need it.
+    if (staged.upload && receipt && (receipt.status === "failed" || receipt.status === "rejected")) {
+      await cloud.discardUpload(staged.upload).catch(() => {});
+    }
+    return receipt;
+  } catch (e) {
+    if (staged.upload) await cloud.discardUpload(staged.upload).catch(() => {});
+    throw e;
+  }
 }
 
 function findNote(needle) {
@@ -577,7 +644,35 @@ function mentionsMe(text) {
 // the owner asking (the same rule as the Mac's wake trigger).
 function addressedToMe(t, sharedProjects) {
   if (t.project && sharedProjects.has(t.project)) return false;
-  return (t.comments || []).slice(-3).some(c => !String(c.authorID || "").startsWith("agent.") && mentionsMe(c.text));
+  return !!addressingComment(t);
+}
+
+// Assistant hand-offs allowed in a row before a person must write again
+// (1.6, matching WorkFlow 5.3.1). Enough for "Claude, check this" -> "Jarvis,
+// done" -> a reply; never enough for two assistants to wake each other forever.
+const MAX_AGENT_HOPS = 3;
+const isAgentID = id => String(id || "").startsWith("agent.");
+
+// The comment asking this agent for something, if any. A person's @Name
+// counts in any of the last three comments. Another assistant's counts only
+// as the newest comment, and only while the run of assistant comments with an
+// @mention since a person last wrote is within MAX_AGENT_HOPS. Before 1.6 an
+// assistant's comment never counted, so Claude's "@Jarvis, brief above" woke
+// nothing.
+function addressingComment(t) {
+  const comments = t.comments || [];
+  // The newest request wins: a fresh assistant hand-off must count even when
+  // an older @mention from a person is still among the last three.
+  const last = comments[comments.length - 1];
+  if (last && isAgentID(last.authorID) && last.authorID !== AGENT.authorID && mentionsMe(last.text)) {
+    let hops = 0;
+    for (const c of [...comments].reverse()) {
+      if (!isAgentID(c.authorID)) break;
+      if (/(^|[^A-Za-z0-9_])@[A-Za-z]/.test(c.text || "")) hops++;
+    }
+    if (hops <= MAX_AGENT_HOPS) return last;
+  }
+  return comments.slice(-3).reverse().find(c => !isAgentID(c.authorID) && mentionsMe(c.text)) || null;
 }
 
 function showNote(n) {
@@ -814,10 +909,11 @@ const TOOLS = [
   {
     name: "workflow_attach_file",
     description: "Attach a local file to a task (a report, a document, an image). The file is copied into the bridge folder and consumed by the app.",
-    inputSchema: { type: "object", properties: { task: { type: "string" }, file: { type: "string", description: "Path to the file on this Mac" }, name: { type: "string", description: "Display name; defaults to the filename" } }, required: ["task", "file"] },
+    inputSchema: { type: "object", properties: { task: { type: "string" }, file: { type: "string", description: "Path to the file on this computer" }, name: { type: "string", description: "Display name; defaults to the filename" } }, required: ["task", "file"] },
     handler: async a => {
-      const name = stageFile(a.file);
-      return receiptText(await send("attach_file", { taskID: findTask(a.task).id, fileName: name, displayName: a.name }, 15000));
+      const taskID = findTask(a.task).id;
+      const staged = await stageFile(a.file);
+      return receiptText(await sendWithFile("attach_file", { taskID, displayName: a.name }, staged, 15000));
     },
   },
   {
@@ -871,25 +967,25 @@ const TOOLS = [
     name: "workflow_file_document",
     description: "File a local file straight into a project's workspace (not onto a task), with an optional profile and folder.",
     inputSchema: { type: "object", properties: {
-      project: { type: "string" }, file: { type: "string", description: "Path to the file on this Mac" },
+      project: { type: "string" }, file: { type: "string", description: "Path to the file on this computer" },
       name: { type: "string" }, type: { type: "string" }, status: { type: "string" }, author: { type: "string" },
       description: { type: "string" }, folder: { type: "string" } }, required: ["project", "file"] },
     handler: async a => {
-      const name = stageFile(a.file);
-      return receiptText(await send("attach_file", { project: a.project, fileName: name, displayName: a.name, docType: a.type,
-        docStatus: a.status, docAuthor: a.author, docSummary: a.description, docFolder: a.folder }, 15000));
+      const staged = await stageFile(a.file);
+      return receiptText(await sendWithFile("attach_file", { project: a.project, displayName: a.name, docType: a.type,
+        docStatus: a.status, docAuthor: a.author, docSummary: a.description, docFolder: a.folder }, staged, 15000));
     },
   },
   {
     name: "workflow_add_document_version",
     description: "Upload a new version of a document. The current file is kept in its history; the profile and folder carry over.",
     inputSchema: { type: "object", properties: {
-      document: { type: "string" }, file: { type: "string", description: "Path to the file on this Mac" },
+      document: { type: "string" }, file: { type: "string", description: "Path to the file on this computer" },
       comment: { type: "string", description: "What changed" } }, required: ["document", "file"] },
     handler: async a => {
       const id = findDocument(a.document).id;
-      const name = stageFile(a.file);
-      return receiptText(await send("add_document_version", { documentID: id, fileName: name, versionComment: a.comment }, 15000));
+      const staged = await stageFile(a.file);
+      return receiptText(await sendWithFile("add_document_version", { documentID: id, versionComment: a.comment }, staged, 15000));
     },
   },
   {
@@ -1199,7 +1295,7 @@ function wakeItems(snap) {
   const personal = c => !String(c.authorID || "").startsWith("agent.");
   const items = rows.map(t => {
     const byPeople = (t.comments || []).filter(personal);
-    const trigger = mine(t) ? byPeople.slice(-1)[0] : byPeople.slice(-3).reverse().find(c => mentionsMe(c.text));
+    const trigger = mine(t) ? byPeople.slice(-1)[0] : addressingComment(t);
     const why = mine(t) ? `assigned to ${AGENT.name}` : `@${AGENT.name} in a comment`;
     return { key: `task:${t.id}`, sig: trigger ? `${trigger.id || ""}@${trigger.timestamp || ""}` : "assigned",
       kind: "task", id: t.id, title: t.title, project: t.project || "", why };
@@ -1246,6 +1342,8 @@ Do the work, then report back in the task's own thread so it reaches the user's
   workflow_complete_task     only when the task is plainly finished
 For a [note], answer with workflow_reply_note, or workflow_convert_note if it describes work worth tracking.
 
+Only @mention another assistant (such as @Claude) when you need it to act: an @mention wakes it. A thank-you or an FYI must not include one.
+
 How to write into a thread (it is read on a phone): one reply per request, about six short lines at most, leading with what changed or what you need. Anything longer goes in a note (workflow_create_note) or an attached file (workflow_attach_file), linked from the reply. Never paste logs or code into a comment. If you need something from the user, ask in the comment and leave it open.
 
 You may only have some tools available. If a request needs a tool you don't have (for example running commands on this computer), say so plainly in the thread rather than working around it.
@@ -1433,7 +1531,11 @@ async function wakeSetup(on) {
     }
   }
   saveAtomic(CP.config, JSON.stringify(cfg, null, 2));
-  console.log(`Waking: ${installWakeSchedule()}.\n  Claude Code: ${claudeBin}\n  Allowed without asking: ${cfg.wakeAllowedTools || "mcp__workflow"} (change with --allow-tools)\n  Log: ${WAKE.log}`);
+  // The same switch as the keep-alive: tests (and anyone running by hand)
+  // must never land in the real crontab or Task Scheduler.
+  const scheduled = argv.includes("--no-schedule") || process.env.WF_NO_SCHEDULE
+    ? `not scheduled (--no-schedule); run "workflow-companion wake" yourself` : installWakeSchedule();
+  console.log(`Waking: ${scheduled}.\n  Claude Code: ${claudeBin}\n  Allowed without asking: ${cfg.wakeAllowedTools || "mcp__workflow"} (change with --allow-tools)\n  Log: ${WAKE.log}`);
   return 0;
 }
 

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@opticell/workflow-companion",
-  "version": "1.5.1",
+  "version": "1.6.0",
+  "mcpName": "io.github.TeamDzX/workflow-companion",
   "description": "Lets Claude on Windows or Linux work in your WorkFlow tasks, notes and projects, through WorkFlow for Mac and your own iCloud. An MCP server.",
   "keywords": [
     "mcp",
@@ -12,7 +13,7 @@
   ],
   "homepage": "https://www.opticell-limited.com/companion",
   "author": "Opticell Limited",
-  "license": "SEE LICENSE IN LICENSE",
+  "license": "MIT",
   "bin": {
     "workflow-companion": "index.js"
   },
@@ -26,5 +27,12 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TeamDzX/workflow-companion.git"
+  },
+  "bugs": {
+    "url": "https://github.com/TeamDzX/workflow-companion/issues"
   }
 }