@parall/agent-core 1.20.2 → 1.22.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;AAM1D,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAwCzD;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+CzD;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CASnE"}

package/dist/event-format.js

@@ -35,6 +35,16 @@ export function buildEventBody(event) {
         lines.push(`[Comment ID: prll://${event.messageId}]`);
         lines.push("", event.body);
     }
+    else if (event.type === "schedule") {
+        lines.push(`[Event: schedule.fired]`);
+        lines.push(`[Schedule: prll://${event.targetId}]`);
+        lines.push(`[Run: prll://${event.messageId}]`);
+        if (event.scheduledFireAt)
+            lines.push(`[Scheduled at: ${sanitizeMeta(event.scheduledFireAt)}]`);
+        if (event.attachedUri)
+            lines.push(`[Attached: ${sanitizeMeta(event.attachedUri)}]`);
+        lines.push("", event.body);
+    }
     else {
         lines.push(`[Event: task.assigned]`);
         const taskLabel = event.targetName

package/dist/gateway-base.d.ts

@@ -69,6 +69,16 @@ export declare class ParallAgentGateway {
     private handleMessage;
     private handleTaskAssignment;
     private handleTaskComment;
+    /**
+     * Fetch the schedule_run snapshot, then feed it as an inbound event. 404 is
+     * tolerated and treated as "dispatched" so the caller can ack the stale
+     * delivery — see `docs/primitives/schedule.md` § "Snapshot 不变性: 内容 vs
+     * 可见性". A later PATCH on target_id / attached_to_uri legitimately revokes
+     * access to already-delivered run snapshots, and the runtime must not crash
+     * or retry forever in that case.
+     */
+    private fetchAndHandleScheduleFire;
+    private handleScheduleFire;
     private catchUpFromDispatch;
     private handleHello;
     private waitForDrain;

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

@@ -1 +1 @@
-{"version":3,"file":"gateway-base.d.ts","sourceRoot":"","sources":["../src/gateway-base.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gateway-base.d.ts","sourceRoot":"","sources":["../src/gateway-base.ts"],"names":[],"mappings":"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"}

package/dist/gateway-base.js

@@ -29,6 +29,9 @@ function resolveStepTarget(event) {
     if (event.targetId.startsWith("cht_")) {
         return { target_type: "chat", target_id: event.targetId };
     }
+    if (event.type === "schedule" || event.targetId.startsWith("sch_")) {
+        return { target_type: "schedule", target_id: event.targetId };
+    }
     return { target_type: "", target_id: event.targetId || undefined };
 }
 async function fetchAllChats(client, orgId, chatInfoMap) {
@@ -150,18 +153,41 @@ export class ParallAgentGateway {
             }
         });
         ws.on("dispatch.new", async (data) => {
-            if (data.event_type !== "task_comment")
-                return;
-            if (!data.source_id || !data.task_id)
-                return;
-            try {
-                const dispatched = await this.handleTaskComment(data.source_id, data.task_id, data.actor_id);
-                if (dispatched) {
-                    this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => { });
+            if (data.event_type === "task_comment") {
+                if (!data.source_id || !data.task_id)
+                    return;
+                try {
+                    const dispatched = await this.handleTaskComment(data.source_id, data.task_id, data.actor_id);
+                    if (dispatched) {
+                        this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => { });
+                    }
+                }
+                catch (err) {
+                    this.opts.log?.error(`parall[${this.opts.accountId}]: task comment dispatch failed for ${data.source_id}: ${String(err)}`);
                 }
             }
-            catch (err) {
-                this.opts.log?.error(`parall[${this.opts.accountId}]: task comment dispatch failed for ${data.source_id}: ${String(err)}`);
+            else if (data.event_type === "schedule.fire") {
+                if (!data.source_id)
+                    return;
+                try {
+                    const dispatched = await this.fetchAndHandleScheduleFire(data.source_id, data.actor_id);
+                    if (dispatched) {
+                        this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => { });
+                    }
+                }
+                catch (err) {
+                    this.opts.log?.error(`parall[${this.opts.accountId}]: schedule fire dispatch failed for ${data.source_id}: ${String(err)}`);
+                }
+            }
+            else if (data.event_type !== "message" && data.event_type !== "task_assign") {
+                // Truly unknown event_type — log so a newly-added dispatch type
+                // not yet wired here surfaces during runtime testing. "message"
+                // and "task_assign" are deliberately excluded: dispatch.new
+                // carries them too, but they are owned by dedicated WS handlers
+                // (message.new, task.assigned) above and would otherwise spam
+                // info-level logs for every inbound chat message / task
+                // assignment on a busy agent.
+                this.opts.log?.info(`parall[${this.opts.accountId}]: dispatch.new with unhandled event_type=${String(data.event_type)} (id=${data.id}) — no-op`);
             }
         });
         this.opts.log?.info(`parall[${this.opts.accountId}]: connecting to ${this.opts.connectionLabel ?? "Parall WS"}...`);
@@ -241,8 +267,14 @@ export class ParallAgentGateway {
                 target_type: target.target_type,
                 target_id: target.target_id,
                 content: {
-                    trigger_type: event.type === "task" ? "task_assign" : event.type === "task_comment" ? "task_comment" : "mention",
-                    trigger_ref: event.type === "task" ? { task_id: event.targetId } : event.type === "task_comment" ? { comment_id: event.messageId, task_id: event.targetId } : { message_id: event.messageId },
+                    trigger_type: event.type === "task" ? "task_assign" :
+                        event.type === "task_comment" ? "task_comment" :
+                            event.type === "schedule" ? "schedule_fire" :
+                                "mention",
+                    trigger_ref: event.type === "task" ? { task_id: event.targetId } :
+                        event.type === "task_comment" ? { comment_id: event.messageId, task_id: event.targetId } :
+                            event.type === "schedule" ? { schedule_id: event.targetId, run_id: event.messageId } :
+                                { message_id: event.messageId },
                     sender_id: event.senderId,
                     sender_name: event.senderName,
                     summary: event.body.substring(0, 200),
@@ -870,6 +902,75 @@ export class ParallAgentGateway {
         }
         return dispatched;
     }
+    /**
+     * Fetch the schedule_run snapshot, then feed it as an inbound event. 404 is
+     * tolerated and treated as "dispatched" so the caller can ack the stale
+     * delivery — see `docs/primitives/schedule.md` § "Snapshot 不变性: 内容 vs
+     * 可见性". A later PATCH on target_id / attached_to_uri legitimately revokes
+     * access to already-delivered run snapshots, and the runtime must not crash
+     * or retry forever in that case.
+     */
+    async fetchAndHandleScheduleFire(runId, actorId) {
+        let run = null;
+        try {
+            run = await this.opts.client.getScheduleRun(this.opts.config.org_id, runId);
+        }
+        catch (err) {
+            const status = err?.status;
+            if (status === 404) {
+                // Contract: ack + warn log + drop. A post-fire PATCH on
+                // target_id / attached_to_uri can legitimately revoke access to an
+                // already-delivered run — this is expected but operationally
+                // visible, so warn (not info) keeps it findable during incident
+                // triage. See docs/primitives/schedule.md § Snapshot 不变性.
+                this.opts.log?.warn(`parall[${this.opts.accountId}]: schedule run ${runId} not accessible (404), acking stale dispatch`);
+                return true;
+            }
+            this.opts.log?.warn(`parall[${this.opts.accountId}]: schedule run fetch failed for ${runId}, leaving pending: ${String(err)}`);
+            return false;
+        }
+        if (!run)
+            return true;
+        return this.handleScheduleFire(run, actorId);
+    }
+    async handleScheduleFire(run, actorId) {
+        if (this.shuttingDown)
+            return false; // drain window — let server requeue via catch-up
+        const dedupeKey = `schedule_run:${run.id}`;
+        if (this.dispatchedTasks.has(dedupeKey))
+            return false;
+        this.dispatchedTasks.add(dedupeKey);
+        this.opts.log?.info(`parall[${this.opts.accountId}]: schedule fired: ${run.id} (schedule ${run.schedule_id})`);
+        const event = {
+            type: "schedule",
+            // Route by schedule_id (not attached chat_id) so concurrent fires of
+            // different schedules can fork independently — matches the PR1 primitive
+            // design where "schedule triggers; target decides response" and fire
+            // semantics are independent of any attached conversation.
+            targetId: run.schedule_id,
+            targetType: "schedule",
+            senderId: actorId ?? "system",
+            senderName: "schedule",
+            messageId: run.id,
+            body: run.fired_description ?? "",
+            scheduledFireAt: run.scheduled_fire_at,
+            attachedUri: run.fired_attached_uri ?? undefined,
+            ackSourceType: "schedule_run",
+            ackSourceId: run.id,
+        };
+        let dispatched;
+        try {
+            dispatched = await this.handleInboundEvent(event);
+        }
+        catch (err) {
+            this.dispatchedTasks.delete(dedupeKey);
+            throw err;
+        }
+        if (!dispatched) {
+            this.dispatchedTasks.delete(dedupeKey);
+        }
+        return dispatched;
+    }
     async catchUpFromDispatch(coldStart = false) {
         const minAge = coldStart ? Date.now() - this.COLD_START_WINDOW_MS : 0;
         let cursor;
@@ -926,6 +1027,9 @@ export class ParallAgentGateway {
                     else if (item.event_type === "task_comment" && item.source_id && item.task_id) {
                         dispatched = await this.handleTaskComment(item.source_id, item.task_id, item.actor_id);
                     }
+                    else if (item.event_type === "schedule.fire" && item.source_id) {
+                        dispatched = await this.fetchAndHandleScheduleFire(item.source_id, item.actor_id);
+                    }
                     else if (item.event_type === "message" && item.source_id && item.chat_id) {
                         if (!this.tryClaimMessage(item.source_id))
                             continue;

package/dist/prompt-fragments.d.ts

@@ -9,7 +9,14 @@
  * audiences, no duplication — this teaches agents HOW to work on Parall, the
  * design docs explain WHY the system works the way it does.
  */
+export interface AgentIdentity {
+    userId: string;
+    displayName: string;
+    description?: string;
+}
+export declare function buildIdentity(agent?: AgentIdentity): string;
+/** @deprecated Use buildIdentity() instead. Kept for backward compat during migration. */
 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### Reading context on demand\n\nAn event only carries the single triggering message. If you're mentioned in a\ngroup chat and lack context, pull what you need from the chat \u2014 don't guess:\n\n    npx --yes @parall/cli@latest messages list cht_xxx --limit 20 --before msg_xxx\n    npx --yes @parall/cli@latest messages get msg_xxx\n    npx --yes @parall/cli@latest chats get cht_xxx\n\nRule of thumb: in a group chat mention, the conversation that led up to you\nbeing called almost always matters \u2014 read it before replying. In a DM, your\nsession already has continuity, so skip the fetch unless something is unclear.\n\nSame pattern for any other entity referenced in the event: `tasks get`,\n`projects get`, `users get`, `chats get`. Follow the reflink, don't ask.\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.";
+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    prll://sch_xxx          schedule\n                                          prll://srn_xxx          schedule run\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### Reading context on demand\n\nAn event only carries the single triggering message. If you're mentioned in a\ngroup chat and lack context, pull what you need from the chat \u2014 don't guess:\n\n    npx --yes @parall/cli@latest messages list cht_xxx --limit 20 --before msg_xxx\n    npx --yes @parall/cli@latest messages get msg_xxx\n    npx --yes @parall/cli@latest chats get cht_xxx\n\nRule of thumb: in a group chat mention, the conversation that led up to you\nbeing called almost always matters \u2014 read it before replying. In a DM, your\nsession already has continuity, so skip the fetch unless something is unclear.\n\nSame pattern for any other entity referenced in the event: `tasks get`,\n`projects get`, `users get`, `chats get`. Follow the reflink, don't ask.\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,aAAa,mcAQlB,CAAC;AAET,eAAO,MAAM,aAAa,4rDAkCmC,CAAC;AAE9D,eAAO,MAAM,oBAAoB,swHA0FkD,CAAC"}
+{"version":3,"file":"prompt-fragments.d.ts","sourceRoot":"","sources":["../src/prompt-fragments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAgBD,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE,aAAa,GAAG,MAAM,CAa3D;AAED,0FAA0F;AAC1F,eAAO,MAAM,aAAa,mcAAqB,CAAC;AAEhD,eAAO,MAAM,aAAa,4rDAkCmC,CAAC;AAE9D,eAAO,MAAM,oBAAoB,03HA2FkD,CAAC"}

package/dist/prompt-fragments.js

@@ -9,7 +9,7 @@
  * 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
+const PRLL_IDENTITY_BASE = `## 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
@@ -18,6 +18,23 @@ 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.`;
+function sanitizeProfileField(value) {
+    return value.replace(/[\r\n]+/g, " ").replace(/`/g, "'").trim();
+}
+export function buildIdentity(agent) {
+    if (!agent)
+        return PRLL_IDENTITY_BASE;
+    const name = sanitizeProfileField(agent.displayName);
+    const lines = [PRLL_IDENTITY_BASE, "", "### Your Parall Identity", ""];
+    lines.push(`You are **${name}** (\`prll://${agent.userId}\`).`);
+    if (agent.description) {
+        lines.push(`Description: ${sanitizeProfileField(agent.description)}`);
+    }
+    lines.push("", `When you see \`${agent.userId}\` or \`prll://${agent.userId}\` in messages, mentions, or events — that's you.`);
+    return lines.join("\n");
+}
+/** @deprecated Use buildIdentity() instead. Kept for backward compat during migration. */
+export const PRLL_IDENTITY = PRLL_IDENTITY_BASE;
 export const PRLL_BEHAVIOR = `## How to work here
 
 ### Move work forward
@@ -77,7 +94,8 @@ 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
+    prll://att_xxx          attachment    prll://sch_xxx          schedule
+                                          prll://srn_xxx          schedule run
 
 **Wiki** — path is file path, fragment is a typed anchor:
 

package/dist/types.d.ts

@@ -18,7 +18,7 @@ export type DispatchState = {
 };
 /** Normalized inbound event from Parall. */
 export type ParallEvent = {
-    type: "message" | "task" | "task_comment";
+    type: "message" | "task" | "task_comment" | "schedule";
     targetId: string;
     targetName?: string;
     targetType?: string;
@@ -34,7 +34,11 @@ export type ParallEvent = {
         fileSize: number;
         mimeType: string;
     }>;
-    ackSourceType?: "message" | "task_activity" | "comment";
+    /** Fire-time snapshot timestamp, used for schedule events. */
+    scheduledFireAt?: string;
+    /** Fire-time attached_to_uri snapshot, used for schedule events. */
+    attachedUri?: string;
+    ackSourceType?: "message" | "task_activity" | "comment" | "schedule_run";
     ackSourceId?: string;
 };
 //# sourceMappingURL=types.d.ts.map

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,GAAG,cAAc,CAAC;IAC1C,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,GAAG,SAAS,CAAC;IACxD,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,GAAG,cAAc,GAAG,UAAU,CAAC;IACvD,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,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,SAAS,GAAG,eAAe,GAAG,SAAS,GAAG,cAAc,CAAC;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC"}

package/package.json

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

package/src/event-format.ts

@@ -34,6 +34,13 @@ export function buildEventBody(event: ParallEvent): string {
     lines.push(`[From: ${event.senderName} (prll://${event.senderId})]`);
     lines.push(`[Comment ID: prll://${event.messageId}]`);
     lines.push("", event.body);
+  } else if (event.type === "schedule") {
+    lines.push(`[Event: schedule.fired]`);
+    lines.push(`[Schedule: prll://${event.targetId}]`);
+    lines.push(`[Run: prll://${event.messageId}]`);
+    if (event.scheduledFireAt) lines.push(`[Scheduled at: ${sanitizeMeta(event.scheduledFireAt)}]`);
+    if (event.attachedUri) lines.push(`[Attached: ${sanitizeMeta(event.attachedUri)}]`);
+    lines.push("", event.body);
   } else {
     lines.push(`[Event: task.assigned]`);
     const taskLabel = event.targetName

package/src/gateway-base.ts

@@ -11,6 +11,7 @@ import type {
   DispatchNewData,
   HelloData,
   MessageNewData,
+  ScheduleRun,
   Task,
   TaskAssignedData,
   TextContent,
@@ -124,6 +125,9 @@ function resolveStepTarget(event: ParallEvent): { target_type: string; target_id
   if (event.targetId.startsWith("cht_")) {
     return { target_type: "chat", target_id: event.targetId };
   }
+  if (event.type === "schedule" || event.targetId.startsWith("sch_")) {
+    return { target_type: "schedule", target_id: event.targetId };
+  }
   return { target_type: "", target_id: event.targetId || undefined };
 }
 
@@ -257,15 +261,35 @@ export class ParallAgentGateway {
     });
 
     ws.on("dispatch.new", async (data: DispatchNewData) => {
-      if (data.event_type !== "task_comment") return;
-      if (!data.source_id || !data.task_id) return;
-      try {
-        const dispatched = await this.handleTaskComment(data.source_id, data.task_id, data.actor_id);
-        if (dispatched) {
-          this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
+      if (data.event_type === "task_comment") {
+        if (!data.source_id || !data.task_id) return;
+        try {
+          const dispatched = await this.handleTaskComment(data.source_id, data.task_id, data.actor_id);
+          if (dispatched) {
+            this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
+          }
+        } catch (err) {
+          this.opts.log?.error(`parall[${this.opts.accountId}]: task comment dispatch failed for ${data.source_id}: ${String(err)}`);
         }
-      } catch (err) {
-        this.opts.log?.error(`parall[${this.opts.accountId}]: task comment dispatch failed for ${data.source_id}: ${String(err)}`);
+      } else if (data.event_type === "schedule.fire") {
+        if (!data.source_id) return;
+        try {
+          const dispatched = await this.fetchAndHandleScheduleFire(data.source_id, data.actor_id);
+          if (dispatched) {
+            this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
+          }
+        } catch (err) {
+          this.opts.log?.error(`parall[${this.opts.accountId}]: schedule fire dispatch failed for ${data.source_id}: ${String(err)}`);
+        }
+      } else if (data.event_type !== "message" && data.event_type !== "task_assign") {
+        // Truly unknown event_type — log so a newly-added dispatch type
+        // not yet wired here surfaces during runtime testing. "message"
+        // and "task_assign" are deliberately excluded: dispatch.new
+        // carries them too, but they are owned by dedicated WS handlers
+        // (message.new, task.assigned) above and would otherwise spam
+        // info-level logs for every inbound chat message / task
+        // assignment on a busy agent.
+        this.opts.log?.info(`parall[${this.opts.accountId}]: dispatch.new with unhandled event_type=${String(data.event_type)} (id=${data.id}) — no-op`);
       }
     });
 
@@ -346,8 +370,16 @@ export class ParallAgentGateway {
         target_type: target.target_type,
         target_id: target.target_id,
         content: {
-          trigger_type: event.type === "task" ? "task_assign" : event.type === "task_comment" ? "task_comment" : "mention",
-          trigger_ref: event.type === "task" ? { task_id: event.targetId } : event.type === "task_comment" ? { comment_id: event.messageId, task_id: event.targetId } : { message_id: event.messageId },
+          trigger_type:
+            event.type === "task" ? "task_assign" :
+            event.type === "task_comment" ? "task_comment" :
+            event.type === "schedule" ? "schedule_fire" :
+            "mention",
+          trigger_ref:
+            event.type === "task" ? { task_id: event.targetId } :
+            event.type === "task_comment" ? { comment_id: event.messageId, task_id: event.targetId } :
+            event.type === "schedule" ? { schedule_id: event.targetId, run_id: event.messageId } :
+            { message_id: event.messageId },
           sender_id: event.senderId,
           sender_name: event.senderName,
           summary: event.body.substring(0, 200),
@@ -1001,6 +1033,74 @@ export class ParallAgentGateway {
     return dispatched;
   }
 
+  /**
+   * Fetch the schedule_run snapshot, then feed it as an inbound event. 404 is
+   * tolerated and treated as "dispatched" so the caller can ack the stale
+   * delivery — see `docs/primitives/schedule.md` § "Snapshot 不变性: 内容 vs
+   * 可见性". A later PATCH on target_id / attached_to_uri legitimately revokes
+   * access to already-delivered run snapshots, and the runtime must not crash
+   * or retry forever in that case.
+   */
+  private async fetchAndHandleScheduleFire(runId: string, actorId: string | null): Promise<boolean> {
+    let run: ScheduleRun | null = null;
+    try {
+      run = await this.opts.client.getScheduleRun(this.opts.config.org_id, runId);
+    } catch (err: unknown) {
+      const status = (err as { status?: number })?.status;
+      if (status === 404) {
+        // Contract: ack + warn log + drop. A post-fire PATCH on
+        // target_id / attached_to_uri can legitimately revoke access to an
+        // already-delivered run — this is expected but operationally
+        // visible, so warn (not info) keeps it findable during incident
+        // triage. See docs/primitives/schedule.md § Snapshot 不变性.
+        this.opts.log?.warn(`parall[${this.opts.accountId}]: schedule run ${runId} not accessible (404), acking stale dispatch`);
+        return true;
+      }
+      this.opts.log?.warn(`parall[${this.opts.accountId}]: schedule run fetch failed for ${runId}, leaving pending: ${String(err)}`);
+      return false;
+    }
+    if (!run) return true;
+    return this.handleScheduleFire(run, actorId);
+  }
+
+  private async handleScheduleFire(run: ScheduleRun, actorId: string | null): Promise<boolean> {
+    if (this.shuttingDown) return false; // drain window — let server requeue via catch-up
+    const dedupeKey = `schedule_run:${run.id}`;
+    if (this.dispatchedTasks.has(dedupeKey)) return false;
+    this.dispatchedTasks.add(dedupeKey);
+    this.opts.log?.info(`parall[${this.opts.accountId}]: schedule fired: ${run.id} (schedule ${run.schedule_id})`);
+
+    const event: ParallEvent = {
+      type: "schedule",
+      // Route by schedule_id (not attached chat_id) so concurrent fires of
+      // different schedules can fork independently — matches the PR1 primitive
+      // design where "schedule triggers; target decides response" and fire
+      // semantics are independent of any attached conversation.
+      targetId: run.schedule_id,
+      targetType: "schedule",
+      senderId: actorId ?? "system",
+      senderName: "schedule",
+      messageId: run.id,
+      body: run.fired_description ?? "",
+      scheduledFireAt: run.scheduled_fire_at,
+      attachedUri: run.fired_attached_uri ?? undefined,
+      ackSourceType: "schedule_run",
+      ackSourceId: run.id,
+    };
+
+    let dispatched: boolean;
+    try {
+      dispatched = await this.handleInboundEvent(event);
+    } catch (err) {
+      this.dispatchedTasks.delete(dedupeKey);
+      throw err;
+    }
+    if (!dispatched) {
+      this.dispatchedTasks.delete(dedupeKey);
+    }
+    return dispatched;
+  }
+
   private async catchUpFromDispatch(coldStart = false) {
     const minAge = coldStart ? Date.now() - this.COLD_START_WINDOW_MS : 0;
     let cursor: string | undefined;
@@ -1053,6 +1153,8 @@ export class ParallAgentGateway {
             }
           } else if (item.event_type === "task_comment" && item.source_id && item.task_id) {
             dispatched = await this.handleTaskComment(item.source_id, item.task_id, item.actor_id);
+          } else if (item.event_type === "schedule.fire" && item.source_id) {
+            dispatched = await this.fetchAndHandleScheduleFire(item.source_id, item.actor_id);
           } else if (item.event_type === "message" && item.source_id && item.chat_id) {
             if (!this.tryClaimMessage(item.source_id)) continue;
             let msg: Awaited<ReturnType<typeof this.opts.client.getMessage>> | null = null;

package/src/prompt-fragments.ts

@@ -10,7 +10,13 @@
  * design docs explain WHY the system works the way it does.
  */
 
-export const PRLL_IDENTITY = `## You on Parall
+export interface AgentIdentity {
+  userId: string;
+  displayName: string;
+  description?: string;
+}
+
+const PRLL_IDENTITY_BASE = `## 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
@@ -20,6 +26,28 @@ The people and agents around you are collaborators, not users to serve. Be hones
 be direct, and care about the outcome of the work — not just the request in front
 of you.`;
 
+function sanitizeProfileField(value: string): string {
+  return value.replace(/[\r\n]+/g, " ").replace(/`/g, "'").trim();
+}
+
+export function buildIdentity(agent?: AgentIdentity): string {
+  if (!agent) return PRLL_IDENTITY_BASE;
+  const name = sanitizeProfileField(agent.displayName);
+  const lines = [PRLL_IDENTITY_BASE, "", "### Your Parall Identity", ""];
+  lines.push(`You are **${name}** (\`prll://${agent.userId}\`).`);
+  if (agent.description) {
+    lines.push(`Description: ${sanitizeProfileField(agent.description)}`);
+  }
+  lines.push(
+    "",
+    `When you see \`${agent.userId}\` or \`prll://${agent.userId}\` in messages, mentions, or events — that's you.`,
+  );
+  return lines.join("\n");
+}
+
+/** @deprecated Use buildIdentity() instead. Kept for backward compat during migration. */
+export const PRLL_IDENTITY = PRLL_IDENTITY_BASE;
+
 export const PRLL_BEHAVIOR = `## How to work here
 
 ### Move work forward
@@ -80,7 +108,8 @@ 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
+    prll://att_xxx          attachment    prll://sch_xxx          schedule
+                                          prll://srn_xxx          schedule run
 
 **Wiki** — path is file path, fragment is a typed anchor:
 

package/src/types.ts

@@ -16,7 +16,7 @@ export type DispatchState = {
 
 /** Normalized inbound event from Parall. */
 export type ParallEvent = {
-  type: "message" | "task" | "task_comment";
+  type: "message" | "task" | "task_comment" | "schedule";
   targetId: string;
   targetName?: string;
   targetType?: string;
@@ -32,6 +32,10 @@ export type ParallEvent = {
     fileSize: number;
     mimeType: string;
   }>;
-  ackSourceType?: "message" | "task_activity" | "comment";
+  /** Fire-time snapshot timestamp, used for schedule events. */
+  scheduledFireAt?: string;
+  /** Fire-time attached_to_uri snapshot, used for schedule events. */
+  attachedUri?: string;
+  ackSourceType?: "message" | "task_activity" | "comment" | "schedule_run";
   ackSourceId?: string;
 };