@parall/agent-core 1.15.0 → 1.16.0

package/dist/event-format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-format.d.ts","sourceRoot":"","sources":["../src/event-format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE1D,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CA0BzD;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CASnE"}
+{"version":3,"file":"event-format.d.ts","sourceRoot":"","sources":["../src/event-format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAM1D,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CA+BzD;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CASnE"}

package/dist/event-format.js

@@ -1,3 +1,6 @@
+function sanitizeMeta(value) {
+    return value.replace(/[\r\n]+/g, " ").replace(/[[\]|]/g, " ").trim();
+}
 export function buildEventBody(event) {
     const lines = [];
     if (event.type === "message") {
@@ -12,8 +15,13 @@ export function buildEventBody(event) {
             lines.push(`[Thread: prll://${event.threadRootId}]`);
         if (event.noReply)
             lines.push(`[Hint: no_reply]`);
-        if (event.mediaFields?.MediaUrl) {
-            lines.push(`[Attachment: ${event.mediaFields.MediaType ?? "file"} ${event.mediaFields.MediaUrl}]`);
+        if (event.attachments?.length) {
+            for (const att of event.attachments) {
+                const sizeStr = att.fileSize >= 1048576
+                    ? `${(att.fileSize / 1048576).toFixed(1)}MB`
+                    : `${Math.round(att.fileSize / 1024)}KB`;
+                lines.push(`[Attachment: prll://${att.id} | ${sanitizeMeta(att.mimeType)} | ${sizeStr} | ${sanitizeMeta(att.fileName)}]`);
+            }
         }
         lines.push("", event.body);
     }

package/dist/gateway-base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gateway-base.d.ts","sourceRoot":"","sources":["../src/gateway-base.ts"],"names":[],"mappings":"AAIA,OAAO,EAAuB,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,EACV,qBAAqB,EAStB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAEV,eAAe,EAGf,aAAa,EAEd,MAAM,uBAAuB,CAAC;AAmD/B,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;IACrB,EAAE,EAAE,QAAQ,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,eAAe,EAAE,eAAe,CAAC;IACjC,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wBAAwB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACtE,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvE,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,QAAQ,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACjH,kBAAkB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACjD,CAAC;AAkCF,qBAAa,kBAAkB;IAuBjB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAtBjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqC;IACtE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsC;IACjE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAK5B;IAEF,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,cAAc,CAA+C;IACrE,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,eAAe,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAS;IAEzB,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAQ;IAChD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;gBAEjB,IAAI,EAAE,oBAAoB;IAIjD,GAAG,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IA8ElD,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,oBAAoB;YAmBd,eAAe;YAqBf,iBAAiB;IAsF/B,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,eAAe;YAQT,gCAAgC;YAMhC,WAAW;YAyDX,gBAAgB;YAmEhB,eAAe;YAmDf,kBAAkB;YAoElB,kBAAkB;YAkBlB,4BAA4B;YA8D5B,aAAa;YA8Bb,oBAAoB;YAmCpB,mBAAmB;YAoGnB,WAAW;YA0DX,QAAQ;CAsBvB"}
+{"version":3,"file":"gateway-base.d.ts","sourceRoot":"","sources":["../src/gateway-base.ts"],"names":[],"mappings":"AAIA,OAAO,EAAuB,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,EACV,qBAAqB,EAQtB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAEV,eAAe,EAGf,aAAa,EAEd,MAAM,uBAAuB,CAAC;AAmD/B,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;IACrB,EAAE,EAAE,QAAQ,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,eAAe,EAAE,eAAe,CAAC;IACjC,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wBAAwB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACtE,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACvE,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,QAAQ,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACjH,kBAAkB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACjD,CAAC;AAkCF,qBAAa,kBAAkB;IAuBjB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAtBjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA+B;IAC3D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqC;IACtE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsC;IACjE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAK5B;IAEF,OAAO,CAAC,SAAS,CAAM;IACvB,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,cAAc,CAA+C;IACrE,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,eAAe,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAS;IAEzB,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAQ;IAChD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;gBAEjB,IAAI,EAAE,oBAAoB;IAIjD,GAAG,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IA8ElD,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,oBAAoB;YAmBd,eAAe;YAqBf,iBAAiB;IAsF/B,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,eAAe;YAQT,gCAAgC;YAMhC,WAAW;YAyDX,gBAAgB;YAmEhB,eAAe;YAmDf,kBAAkB;YAoElB,kBAAkB;YAkBlB,4BAA4B;YAoD5B,aAAa;YA8Bb,oBAAoB;YAmCpB,mBAAmB;YAoGnB,WAAW;YA0DX,QAAQ;CAsBvB"}

package/dist/gateway-base.js

@@ -324,7 +324,7 @@ export class ParallAgentGateway {
         try {
             if (this.activeSessionId) {
                 try {
-                    await this.opts.client.updateAgentSession(this.opts.config.org_id, this.opts.agentUserId, this.activeSessionId, { status: "active" });
+                    await this.opts.client.updateAgentSession(this.opts.config.org_id, this.opts.agentUserId, this.activeSessionId, { status: "active", trigger_message_id: event.messageId });
                 }
                 catch (err) {
                     this.opts.log?.warn(`parall[${this.opts.accountId}]: failed to set session active: ${String(err)}`);
@@ -562,42 +562,29 @@ export class ParallAgentGateway {
         }
     }
     async buildMessageDispatchDecision(chatId, message) {
-        if (message.message_type !== "text" && message.message_type !== "file") {
+        if (message.message_type !== "text") {
             return { action: "skip" };
         }
         const chatInfo = await this.getOrFetchChatInfo(chatId);
         if (!chatInfo)
             return { action: "retry" };
-        let body = "";
-        let mediaFields = {};
-        if (message.message_type === "text") {
-            const content = message.content;
-            body = content.text?.trim() ?? "";
-            if (!body)
-                return { action: "skip" };
-            if (chatInfo.type === "group" && chatInfo.agentRoutingMode !== "active") {
-                const mentions = content.mentions ?? [];
-                const isMentioned = mentions.some((mention) => mention.user_id === this.opts.agentUserId || mention.user_id === MENTION_ALL_USER_ID);
-                if (!isMentioned)
-                    return { action: "skip" };
-            }
-        }
-        else {
-            const content = message.content;
-            if (chatInfo.type === "group" && chatInfo.agentRoutingMode !== "active") {
+        const content = message.content;
+        const body = content.text?.trim() ?? "";
+        const hasAttachments = message.attachments?.length;
+        if (!body && !hasAttachments)
+            return { action: "skip" };
+        if (chatInfo.type === "group" && chatInfo.agentRoutingMode !== "active") {
+            const mentions = content.mentions ?? [];
+            const isMentioned = mentions.some((mention) => mention.user_id === this.opts.agentUserId || mention.user_id === MENTION_ALL_USER_ID);
+            if (!isMentioned)
                 return { action: "skip" };
-            }
-            body = content.caption?.trim() || `[file: ${content.file_name || "attachment"}]`;
-            if (content.attachment_id) {
-                try {
-                    const fileRes = await this.opts.client.getFileUrl(content.attachment_id);
-                    mediaFields = { MediaUrl: fileRes.url, MediaType: content.mime_type };
-                }
-                catch (err) {
-                    this.opts.log?.warn(`parall[${this.opts.accountId}]: failed to get file URL for ${content.attachment_id}: ${String(err)}`);
-                }
-            }
         }
+        const attachments = (message.attachments ?? []).map((a) => ({
+            id: a.id,
+            fileName: a.file_name,
+            fileSize: a.file_size,
+            mimeType: a.mime_type,
+        }));
         return {
             action: "dispatch",
             event: {
@@ -608,10 +595,10 @@ export class ParallAgentGateway {
                 senderId: message.sender_id,
                 senderName: message.sender?.display_name ?? message.sender_id,
                 messageId: message.id,
-                body,
+                body: body || "[attachment]",
                 threadRootId: message.thread_root_id ?? undefined,
                 noReply: message.hints?.no_reply ?? false,
-                mediaFields: Object.keys(mediaFields).length > 0 ? mediaFields : undefined,
+                attachments: attachments.length > 0 ? attachments : undefined,
                 ackSourceType: "message",
                 ackSourceId: message.id,
             },
@@ -621,7 +608,7 @@ export class ParallAgentGateway {
         const chatId = data.chat_id;
         if (data.sender_id === this.opts.agentUserId)
             return;
-        if (data.message_type !== "text" && data.message_type !== "file")
+        if (data.message_type !== "text")
             return;
         if (!this.tryClaimMessage(data.id))
             return;

package/dist/prompt-fragments.d.ts

@@ -3,11 +3,13 @@
  * Each runtime adapter imports these and injects them via its own mechanism
  * (OpenClaw: appendSystemContext, Claude Code: workspace file, etc.).
  *
- * This is the agent-facing SSOT for prll:// URI usage. The developer-facing
- * architectural spec (BNF, canonicalization, data model) lives in
- * docs/engineering-design/reference-schema-design.md. Different audiences,
- * no duplication — this teaches agents HOW to use refs, the design doc
- * explains WHY the system works the way it does.
+ * This is the agent-facing SSOT for Parall identity, behavior, and prll:// URI
+ * usage. The developer-facing architectural spec (BNF, canonicalization, data
+ * model) lives in docs/engineering-design/reference-schema-design.md. Different
+ * audiences, no duplication — this teaches agents HOW to work on Parall, the
+ * design docs explain WHY the system works the way it does.
  */
-export declare const PRLL_REFERENCE_GUIDE = "## Parall References\n\nEvery entity on Parall has a `prll://` URI. Use these URIs to link related\nentities when you create or update tasks, comments, messages, and wiki files.\n\nAll three forms work \u2014 pick whichever fits:\n\n    prll://tsk_abc                               bare URI (auto-linked)\n    [](prll://tsk_abc)                           empty context (renders resolved title)\n    [relevant context](prll://tsk_abc)           with author annotation\n\nBare URIs and empty-context refs are preferred in most cases \u2014 the platform\nresolves and renders the entity title automatically.\n\n### URI format\n\n`prll://` follows standard URI structure: `scheme://authority/path?query#fragment`.\n\n**Entities** \u2014 the entity ID is the authority:\n\n    prll://usr_xxx          user          prll://prj_xxx          project\n    prll://tsk_xxx          task          prll://wik_xxx          wiki\n    prll://msg_xxx          message       prll://tcm_xxx          task comment\n    prll://cht_xxx          chat          prll://ase_xxx          agent session\n\n**Wiki** \u2014 path is file path, fragment is a typed anchor:\n\n    prll://wik_xxx/docs/guide.md                  file\n    prll://wik_xxx/docs/guide.md#h=Auth::OAuth    heading (:: = hierarchy)\n    prll://wik_xxx/src/auth.go?rev=<sha>#l=42-58  line range (revision-pinned)\n\n  Anchor types: `h=` heading, `l=` line/range, `s=` symbol.\n  Line anchors in persistent content require `?rev=<full-40-char-sha>`.\n\n**Chat message range**:\n\n    prll://cht_xxx#range=msg_01HA,msg_01HZ\n\n**Field access** \u2014 path selects a field (omit to reference the entity itself):\n\n    prll://tsk_xxx/description#Implementation     heading within task description\n\n### When to reference\n\n- **Origin** \u2014 always link the message or task that triggered your work\n- **Design docs / wiki** \u2014 link specs and guides relevant to the work\n- **Related tasks** \u2014 link parent, sibling, or blocking tasks\n- **People** \u2014 link assignees or stakeholders when mentioning them\n- **Conversations** \u2014 link a chat or message range as context\n\n### Why this matters\n\nOther agents and humans read your output. References build a navigable context graph \u2014\nin multi-agent workflows, your references are the map that the next agent follows.";
+export declare const PRLL_IDENTITY = "## You on Parall\n\nParall is a shared workspace where humans and agents work side by side as equals.\nYou are a participant here, not a service. You hold tasks, own decisions, and are\naccountable for the work you take on \u2014 the same way a human teammate is.\n\nThe people and agents around you are collaborators, not users to serve. Be honest,\nbe direct, and care about the outcome of the work \u2014 not just the request in front\nof you.";
+export declare const PRLL_BEHAVIOR = "## How to work here\n\n### Move work forward\nDon't wait for instructions. If you see the next step, take it. If something is\nambiguous, clarify once and proceed. If you're blocked, say what's blocking you\n\u2014 don't go silent. Initiative is expected.\n\n### Work in the open\nNothing you do exists until the system can see it. Your progress, decisions,\nblockers, and results need to live in tasks, comments, messages, or wiki pages\n\u2014 otherwise the organization is blind to your work, and so is the next agent\nwho picks up where you left off. Leave traces as you go, not at the end.\n\nFor non-trivial work: create or claim a task, mark it `in_progress`, comment\nwhen status materially changes, close it when done, and link the origin that\ntriggered it. Details: load the `parall-tasks` skill.\n\n### Communicate like a teammate\nMatch the conversation \u2014 concise in chat, thorough in docs, plain language over\njargon. Say what matters; stop when you're done. Don't narrate every tool call\nor pad replies to seem thorough.\n\n### Respect what's shared\nYou have broad latitude inside your own work. But actions that are visible to\nothers, hard to reverse, or touch shared state \u2014 sending DMs, editing shared\nwiki, reassigning others' tasks, deleting content \u2014 pause and confirm before\nacting, unless you've been explicitly authorized.\n\n### Shared workspace\nOther agents share this workspace. Before starting work, check whether someone\n\u2014 human or agent \u2014 has already picked it up. Coordination beats racing.\n\n### When in doubt\nPrefer asking over guessing. Prefer \"I don't know\" over fabricating. Your\ncredibility is what you bring to the workspace \u2014 protect it.";
+export declare const PRLL_REFERENCE_GUIDE = "## Parall References\n\nEvery entity on Parall has a `prll://` URI. Use these URIs to link related\nentities when you create or update tasks, comments, messages, and wiki files.\n\nAll three forms work \u2014 pick whichever fits:\n\n    prll://tsk_abc                               bare URI (auto-linked)\n    [](prll://tsk_abc)                           empty context (renders resolved title)\n    [relevant context](prll://tsk_abc)           with author annotation\n\nBare URIs and empty-context refs are preferred in most cases \u2014 the platform\nresolves and renders the entity title automatically.\n\n### URI format\n\n`prll://` follows standard URI structure: `scheme://authority/path?query#fragment`.\n\n**Entities** \u2014 the entity ID is the authority:\n\n    prll://usr_xxx          user          prll://prj_xxx          project\n    prll://tsk_xxx          task          prll://wik_xxx          wiki\n    prll://msg_xxx          message       prll://tcm_xxx          task comment\n    prll://cht_xxx          chat          prll://ase_xxx          agent session\n    prll://att_xxx          attachment\n\n**Wiki** \u2014 path is file path, fragment is a typed anchor:\n\n    prll://wik_xxx/docs/guide.md                  file\n    prll://wik_xxx/docs/guide.md#h=Auth::OAuth    heading (:: = hierarchy)\n    prll://wik_xxx/src/auth.go?rev=<sha>#l=42-58  line range (revision-pinned)\n\n  Anchor types: `h=` heading, `l=` line/range, `s=` symbol.\n  Line anchors in persistent content require `?rev=<full-40-char-sha>`.\n\n**Chat message range**:\n\n    prll://cht_xxx#range=msg_01HA,msg_01HZ\n\n**Field access** \u2014 path selects a field (omit to reference the entity itself):\n\n    prll://tsk_xxx/description#Implementation     heading within task description\n\n### File attachments\n\nMessages may include attachments. They appear in events as:\n\n    [Attachment: prll://att_xxx | image/png | 1.2MB | screenshot.png]\n\nTo download an attachment, use the CLI:\n\n    npx @parall/cli@latest files download att_xxx --output /tmp/screenshot.png\n\nTo send a file:\n\n    npx @parall/cli@latest messages send prll://cht_xxx --file /tmp/output.png --text \"Done\"\n\nOr upload first and reuse across chats:\n\n    npx @parall/cli@latest files upload /tmp/report.pdf\n    npx @parall/cli@latest messages send prll://cht_aaa --attachment att_yyy --text \"Report\"\n    npx @parall/cli@latest messages send prll://cht_bbb --attachment att_yyy --text \"FYI\"\n\n### When to reference\n\n- **Origin** \u2014 always link the message or task that triggered your work\n- **Design docs / wiki** \u2014 link specs and guides relevant to the work\n- **Related tasks** \u2014 link parent, sibling, or blocking tasks\n- **People** \u2014 link assignees or stakeholders when mentioning them\n- **Conversations** \u2014 link a chat or message range as context\n\n### Why this matters\n\nOther agents and humans read your output. References build a navigable context graph \u2014\nin multi-agent workflows, your references are the map that the next agent follows.";
 //# sourceMappingURL=prompt-fragments.d.ts.map

package/dist/prompt-fragments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-fragments.d.ts","sourceRoot":"","sources":["../src/prompt-fragments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,oBAAoB,6xEAqDkD,CAAC"}
+{"version":3,"file":"prompt-fragments.d.ts","sourceRoot":"","sources":["../src/prompt-fragments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,aAAa,mcAQlB,CAAC;AAET,eAAO,MAAM,aAAa,4rDAkCmC,CAAC;AAE9D,eAAO,MAAM,oBAAoB,0/FA0EkD,CAAC"}

package/dist/prompt-fragments.js

@@ -3,12 +3,56 @@
  * Each runtime adapter imports these and injects them via its own mechanism
  * (OpenClaw: appendSystemContext, Claude Code: workspace file, etc.).
  *
- * This is the agent-facing SSOT for prll:// URI usage. The developer-facing
- * architectural spec (BNF, canonicalization, data model) lives in
- * docs/engineering-design/reference-schema-design.md. Different audiences,
- * no duplication — this teaches agents HOW to use refs, the design doc
- * explains WHY the system works the way it does.
+ * This is the agent-facing SSOT for Parall identity, behavior, and prll:// URI
+ * usage. The developer-facing architectural spec (BNF, canonicalization, data
+ * model) lives in docs/engineering-design/reference-schema-design.md. Different
+ * audiences, no duplication — this teaches agents HOW to work on Parall, the
+ * design docs explain WHY the system works the way it does.
  */
+export const PRLL_IDENTITY = `## You on Parall
+
+Parall is a shared workspace where humans and agents work side by side as equals.
+You are a participant here, not a service. You hold tasks, own decisions, and are
+accountable for the work you take on — the same way a human teammate is.
+
+The people and agents around you are collaborators, not users to serve. Be honest,
+be direct, and care about the outcome of the work — not just the request in front
+of you.`;
+export const PRLL_BEHAVIOR = `## How to work here
+
+### Move work forward
+Don't wait for instructions. If you see the next step, take it. If something is
+ambiguous, clarify once and proceed. If you're blocked, say what's blocking you
+— don't go silent. Initiative is expected.
+
+### Work in the open
+Nothing you do exists until the system can see it. Your progress, decisions,
+blockers, and results need to live in tasks, comments, messages, or wiki pages
+— otherwise the organization is blind to your work, and so is the next agent
+who picks up where you left off. Leave traces as you go, not at the end.
+
+For non-trivial work: create or claim a task, mark it \`in_progress\`, comment
+when status materially changes, close it when done, and link the origin that
+triggered it. Details: load the \`parall-tasks\` skill.
+
+### Communicate like a teammate
+Match the conversation — concise in chat, thorough in docs, plain language over
+jargon. Say what matters; stop when you're done. Don't narrate every tool call
+or pad replies to seem thorough.
+
+### Respect what's shared
+You have broad latitude inside your own work. But actions that are visible to
+others, hard to reverse, or touch shared state — sending DMs, editing shared
+wiki, reassigning others' tasks, deleting content — pause and confirm before
+acting, unless you've been explicitly authorized.
+
+### Shared workspace
+Other agents share this workspace. Before starting work, check whether someone
+— human or agent — has already picked it up. Coordination beats racing.
+
+### When in doubt
+Prefer asking over guessing. Prefer "I don't know" over fabricating. Your
+credibility is what you bring to the workspace — protect it.`;
 export const PRLL_REFERENCE_GUIDE = `## Parall References
 
 Every entity on Parall has a \`prll://\` URI. Use these URIs to link related
@@ -33,6 +77,7 @@ resolves and renders the entity title automatically.
     prll://tsk_xxx          task          prll://wik_xxx          wiki
     prll://msg_xxx          message       prll://tcm_xxx          task comment
     prll://cht_xxx          chat          prll://ase_xxx          agent session
+    prll://att_xxx          attachment
 
 **Wiki** — path is file path, fragment is a typed anchor:
 
@@ -51,6 +96,26 @@ resolves and renders the entity title automatically.
 
     prll://tsk_xxx/description#Implementation     heading within task description
 
+### File attachments
+
+Messages may include attachments. They appear in events as:
+
+    [Attachment: prll://att_xxx | image/png | 1.2MB | screenshot.png]
+
+To download an attachment, use the CLI:
+
+    npx @parall/cli@latest files download att_xxx --output /tmp/screenshot.png
+
+To send a file:
+
+    npx @parall/cli@latest messages send prll://cht_xxx --file /tmp/output.png --text "Done"
+
+Or upload first and reuse across chats:
+
+    npx @parall/cli@latest files upload /tmp/report.pdf
+    npx @parall/cli@latest messages send prll://cht_aaa --attachment att_yyy --text "Report"
+    npx @parall/cli@latest messages send prll://cht_bbb --attachment att_yyy --text "FYI"
+
 ### When to reference
 
 - **Origin** — always link the message or task that triggered your work

package/dist/types.d.ts

@@ -28,7 +28,12 @@ export type ParallEvent = {
     body: string;
     threadRootId?: string;
     noReply?: boolean;
-    mediaFields?: Record<string, string | undefined>;
+    attachments?: Array<{
+        id: string;
+        fileName: string;
+        fileSize: number;
+        mimeType: string;
+    }>;
     ackSourceType?: "message" | "task_activity";
     ackSourceId?: string;
 };

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,MAAM,MAAM,UAAU,GAAG;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,kBAAkB,EAAE,UAAU,EAAE,CAAC;IACjC,UAAU,EAAE,WAAW,EAAE,CAAC;CAC3B,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACjD,aAAa,CAAC,EAAE,SAAS,GAAG,eAAe,CAAC;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,MAAM,MAAM,UAAU,GAAG;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,kBAAkB,EAAE,UAAU,EAAE,CAAC;IACjC,UAAU,EAAE,WAAW,EAAE,CAAC;CAC3B,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,KAAK,CAAC;QAClB,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,aAAa,CAAC,EAAE,SAAS,GAAG,eAAe,CAAC;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/agent-core",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Shared agent runtime orchestration helpers for Parall",
   "license": "MIT",
   "repository": {
@@ -22,7 +22,7 @@
     "src"
   ],
   "dependencies": {
-    "@parall/sdk": "1.15.0"
+    "@parall/sdk": "1.16.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/event-format.ts

@@ -1,5 +1,9 @@
 import type { ForkResult, ParallEvent } from "./types.js";
 
+function sanitizeMeta(value: string): string {
+  return value.replace(/[\r\n]+/g, " ").replace(/[[\]|]/g, " ").trim();
+}
+
 export function buildEventBody(event: ParallEvent): string {
   const lines: string[] = [];
   if (event.type === "message") {
@@ -12,8 +16,13 @@ export function buildEventBody(event: ParallEvent): string {
     lines.push(`[Message ID: prll://${event.messageId}]`);
     if (event.threadRootId) lines.push(`[Thread: prll://${event.threadRootId}]`);
     if (event.noReply) lines.push(`[Hint: no_reply]`);
-    if (event.mediaFields?.MediaUrl) {
-      lines.push(`[Attachment: ${event.mediaFields.MediaType ?? "file"} ${event.mediaFields.MediaUrl}]`);
+    if (event.attachments?.length) {
+      for (const att of event.attachments) {
+        const sizeStr = att.fileSize >= 1048576
+          ? `${(att.fileSize / 1048576).toFixed(1)}MB`
+          : `${Math.round(att.fileSize / 1024)}KB`;
+        lines.push(`[Attachment: prll://${att.id} | ${sanitizeMeta(att.mimeType)} | ${sizeStr} | ${sanitizeMeta(att.fileName)}]`);
+      }
     }
     lines.push("", event.body);
   } else {

package/src/gateway-base.ts

@@ -8,7 +8,6 @@ import type {
   Chat,
   ChatUpdateData,
   HelloData,
-  MediaContent,
   MessageNewData,
   Task,
   TaskAssignedData,
@@ -437,7 +436,7 @@ export class ParallAgentGateway {
     try {
       if (this.activeSessionId) {
         try {
-          await this.opts.client.updateAgentSession(this.opts.config.org_id, this.opts.agentUserId, this.activeSessionId, { status: "active" });
+          await this.opts.client.updateAgentSession(this.opts.config.org_id, this.opts.agentUserId, this.activeSessionId, { status: "active", trigger_message_id: event.messageId });
         } catch (err) {
           this.opts.log?.warn(`parall[${this.opts.accountId}]: failed to set session active: ${String(err)}`);
         }
@@ -685,44 +684,34 @@ export class ParallAgentGateway {
     chatId: string,
     message: DispatchableMessage,
   ): Promise<MessageDispatchDecision> {
-    if (message.message_type !== "text" && message.message_type !== "file") {
+    if (message.message_type !== "text") {
       return { action: "skip" };
     }
 
     const chatInfo = await this.getOrFetchChatInfo(chatId);
     if (!chatInfo) return { action: "retry" };
 
-    let body = "";
-    let mediaFields: Record<string, string | undefined> = {};
+    const content = message.content as TextContent;
+    const body = content.text?.trim() ?? "";
+    const hasAttachments = (message as { attachments?: unknown[] }).attachments?.length;
 
-    if (message.message_type === "text") {
-      const content = message.content as TextContent;
-      body = content.text?.trim() ?? "";
-      if (!body) return { action: "skip" };
+    if (!body && !hasAttachments) return { action: "skip" };
 
-      if (chatInfo.type === "group" && chatInfo.agentRoutingMode !== "active") {
-        const mentions = content.mentions ?? [];
-        const isMentioned = mentions.some(
-          (mention) => mention.user_id === this.opts.agentUserId || mention.user_id === MENTION_ALL_USER_ID,
-        );
-        if (!isMentioned) return { action: "skip" };
-      }
-    } else {
-      const content = message.content as MediaContent;
-      if (chatInfo.type === "group" && chatInfo.agentRoutingMode !== "active") {
-        return { action: "skip" };
-      }
-      body = content.caption?.trim() || `[file: ${content.file_name || "attachment"}]`;
-      if (content.attachment_id) {
-        try {
-          const fileRes = await this.opts.client.getFileUrl(content.attachment_id);
-          mediaFields = { MediaUrl: fileRes.url, MediaType: content.mime_type };
-        } catch (err) {
-          this.opts.log?.warn(`parall[${this.opts.accountId}]: failed to get file URL for ${content.attachment_id}: ${String(err)}`);
-        }
-      }
+    if (chatInfo.type === "group" && chatInfo.agentRoutingMode !== "active") {
+      const mentions = content.mentions ?? [];
+      const isMentioned = mentions.some(
+        (mention) => mention.user_id === this.opts.agentUserId || mention.user_id === MENTION_ALL_USER_ID,
+      );
+      if (!isMentioned) return { action: "skip" };
     }
 
+    const attachments = ((message as { attachments?: Array<{ id: string; file_name: string; file_size: number; mime_type: string }> }).attachments ?? []).map((a) => ({
+      id: a.id,
+      fileName: a.file_name,
+      fileSize: a.file_size,
+      mimeType: a.mime_type,
+    }));
+
     return {
       action: "dispatch",
       event: {
@@ -733,10 +722,10 @@ export class ParallAgentGateway {
         senderId: message.sender_id,
         senderName: message.sender?.display_name ?? message.sender_id,
         messageId: message.id,
-        body,
+        body: body || "[attachment]",
         threadRootId: message.thread_root_id ?? undefined,
         noReply: message.hints?.no_reply ?? false,
-        mediaFields: Object.keys(mediaFields).length > 0 ? mediaFields : undefined,
+        attachments: attachments.length > 0 ? attachments : undefined,
         ackSourceType: "message",
         ackSourceId: message.id,
       },
@@ -746,7 +735,7 @@ export class ParallAgentGateway {
   private async handleMessage(data: MessageNewData) {
     const chatId = data.chat_id;
     if (data.sender_id === this.opts.agentUserId) return;
-    if (data.message_type !== "text" && data.message_type !== "file") return;
+    if (data.message_type !== "text") return;
     if (!this.tryClaimMessage(data.id)) return;
 
     const decision = await this.buildMessageDispatchDecision(chatId, data);

package/src/prompt-fragments.ts

@@ -3,13 +3,59 @@
  * Each runtime adapter imports these and injects them via its own mechanism
  * (OpenClaw: appendSystemContext, Claude Code: workspace file, etc.).
  *
- * This is the agent-facing SSOT for prll:// URI usage. The developer-facing
- * architectural spec (BNF, canonicalization, data model) lives in
- * docs/engineering-design/reference-schema-design.md. Different audiences,
- * no duplication — this teaches agents HOW to use refs, the design doc
- * explains WHY the system works the way it does.
+ * This is the agent-facing SSOT for Parall identity, behavior, and prll:// URI
+ * usage. The developer-facing architectural spec (BNF, canonicalization, data
+ * model) lives in docs/engineering-design/reference-schema-design.md. Different
+ * audiences, no duplication — this teaches agents HOW to work on Parall, the
+ * design docs explain WHY the system works the way it does.
  */
 
+export const PRLL_IDENTITY = `## You on Parall
+
+Parall is a shared workspace where humans and agents work side by side as equals.
+You are a participant here, not a service. You hold tasks, own decisions, and are
+accountable for the work you take on — the same way a human teammate is.
+
+The people and agents around you are collaborators, not users to serve. Be honest,
+be direct, and care about the outcome of the work — not just the request in front
+of you.`;
+
+export const PRLL_BEHAVIOR = `## How to work here
+
+### Move work forward
+Don't wait for instructions. If you see the next step, take it. If something is
+ambiguous, clarify once and proceed. If you're blocked, say what's blocking you
+— don't go silent. Initiative is expected.
+
+### Work in the open
+Nothing you do exists until the system can see it. Your progress, decisions,
+blockers, and results need to live in tasks, comments, messages, or wiki pages
+— otherwise the organization is blind to your work, and so is the next agent
+who picks up where you left off. Leave traces as you go, not at the end.
+
+For non-trivial work: create or claim a task, mark it \`in_progress\`, comment
+when status materially changes, close it when done, and link the origin that
+triggered it. Details: load the \`parall-tasks\` skill.
+
+### Communicate like a teammate
+Match the conversation — concise in chat, thorough in docs, plain language over
+jargon. Say what matters; stop when you're done. Don't narrate every tool call
+or pad replies to seem thorough.
+
+### Respect what's shared
+You have broad latitude inside your own work. But actions that are visible to
+others, hard to reverse, or touch shared state — sending DMs, editing shared
+wiki, reassigning others' tasks, deleting content — pause and confirm before
+acting, unless you've been explicitly authorized.
+
+### Shared workspace
+Other agents share this workspace. Before starting work, check whether someone
+— human or agent — has already picked it up. Coordination beats racing.
+
+### When in doubt
+Prefer asking over guessing. Prefer "I don't know" over fabricating. Your
+credibility is what you bring to the workspace — protect it.`;
+
 export const PRLL_REFERENCE_GUIDE = `## Parall References
 
 Every entity on Parall has a \`prll://\` URI. Use these URIs to link related
@@ -34,6 +80,7 @@ resolves and renders the entity title automatically.
     prll://tsk_xxx          task          prll://wik_xxx          wiki
     prll://msg_xxx          message       prll://tcm_xxx          task comment
     prll://cht_xxx          chat          prll://ase_xxx          agent session
+    prll://att_xxx          attachment
 
 **Wiki** — path is file path, fragment is a typed anchor:
 
@@ -52,6 +99,26 @@ resolves and renders the entity title automatically.
 
     prll://tsk_xxx/description#Implementation     heading within task description
 
+### File attachments
+
+Messages may include attachments. They appear in events as:
+
+    [Attachment: prll://att_xxx | image/png | 1.2MB | screenshot.png]
+
+To download an attachment, use the CLI:
+
+    npx @parall/cli@latest files download att_xxx --output /tmp/screenshot.png
+
+To send a file:
+
+    npx @parall/cli@latest messages send prll://cht_xxx --file /tmp/output.png --text "Done"
+
+Or upload first and reuse across chats:
+
+    npx @parall/cli@latest files upload /tmp/report.pdf
+    npx @parall/cli@latest messages send prll://cht_aaa --attachment att_yyy --text "Report"
+    npx @parall/cli@latest messages send prll://cht_bbb --attachment att_yyy --text "FYI"
+
 ### When to reference
 
 - **Origin** — always link the message or task that triggered your work

package/src/types.ts

@@ -26,7 +26,12 @@ export type ParallEvent = {
   body: string;
   threadRootId?: string;
   noReply?: boolean;
-  mediaFields?: Record<string, string | undefined>;
+  attachments?: Array<{
+    id: string;
+    fileName: string;
+    fileSize: number;
+    mimeType: string;
+  }>;
   ackSourceType?: "message" | "task_activity";
   ackSourceId?: string;
 };