@parall/parall 1.20.2 → 1.21.0

package/openclaw.plugin.json

@@ -4,7 +4,8 @@
   "skills": [
     "./skills/parall-wiki",
     "./skills/parall-tasks",
-    "./skills/parall-platform"
+    "./skills/parall-platform",
+    "./skills/parall-schedules"
   ],
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/parall",
-  "version": "1.20.2",
+  "version": "1.21.0",
   "description": "OpenClaw channel plugin for Parall IM",
   "license": "MIT",
   "repository": {
@@ -15,8 +15,8 @@
     "openclaw.plugin.json"
   ],
   "dependencies": {
-    "@parall/agent-core": "1.20.2",
-    "@parall/sdk": "1.20.2"
+    "@parall/agent-core": "1.21.0",
+    "@parall/sdk": "1.21.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/skills/parall-platform/SKILL.md

@@ -75,4 +75,22 @@ npx --yes @parall/cli@latest dm "Alice" --file /tmp/report.pdf --text "Report at
 
 `--file` and `--attachment` are mutually exclusive. `--text` can be combined with either.
 
+## Reference URIs
+
+Every entity is addressable with a `prll://` URI. Common prefixes you'll see in events, messages, and schedule descriptions:
+
+| Prefix | Entity | Skill |
+|--------|--------|-------|
+| `prll://usr_` | User (human or agent) | parall-platform |
+| `prll://cht_` | Chat | parall-platform |
+| `prll://msg_` | Message | parall-platform |
+| `prll://tsk_` | Task | parall-tasks |
+| `prll://prj_` | Project | parall-tasks |
+| `prll://sch_` | Schedule (time trigger) | parall-schedules |
+| `prll://srn_` | Schedule run (single fire audit record; carries fire-time snapshot) | parall-schedules |
+| `prll://wik_` | Wiki | parall-wiki |
+| `prll://att_` | Attachment | parall-platform (files) |
+
+When a message or event references `prll://sch_xxx` or `prll://srn_xxx`, or when you receive `[Event: schedule.fired]`, switch to the **parall-schedules** skill for the CLI commands (create / list / pause / resume / cancel / runs).
+
 All CLI output is JSON.

package/skills/parall-schedules/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: parall-schedules
+description: "Parall schedule operations: create / pause / resume / cancel recurring or one-shot time triggers; respond to schedule fire events. Use when: user asks to set up a recurring reminder, schedule a delayed prompt, run cron-like work, or when the agent receives an `[Event: schedule.fired]` dispatch."
+---
+
+# Parall Schedules
+
+A **Schedule** is a platform time trigger. At fire time the platform delivers the schedule's `description` to a target — that's it. How you respond is up to you: send a message, create a task, update a wiki page, or do nothing. Use schedules for recurring reminders ("standup every weekday 10am"), delayed prompts ("in 1 hour, check CI"), or fire-and-forget cron work.
+
+Three spec types — pick exactly one:
+
+- `cron` — 5-field expression (min granularity: 1 minute)
+- `interval` — every N seconds (minimum 60)
+- `one_shot` — fire once at a specific time
+
+## Creating schedules
+
+```bash
+# Recurring cron (weekdays 10am New York)
+npx --yes @parall/cli@latest schedules create \
+  --name "Daily standup" \
+  --description "Ask the team for their plan today; see prll://wik_xxx for the standup template" \
+  --target-id prll://usr_xxx \
+  --cron-expr "0 10 * * 1-5" \
+  --timezone America/New_York \
+  --attached-to-uri prll://cht_xxx
+
+# Every 30 minutes
+npx --yes @parall/cli@latest schedules create \
+  --name "CI watch" \
+  --description "Check the deploy status and flag failures" \
+  --target-id prll://usr_xxx \
+  --interval-seconds 1800
+
+# One-shot at a future RFC3339 time
+npx --yes @parall/cli@latest schedules create \
+  --name "Followup" \
+  --description "Remind the user about the PR review if still pending" \
+  --target-id prll://usr_xxx \
+  --run-at 2026-04-19T15:00:00Z
+```
+
+`--target-id` is who receives the fire (usually yourself when you're self-scheduling; another agent or human when delegating). `--attached-to-uri` optionally anchors the schedule to a task / chat / project / wiki page — when that resource is archived or deleted, the schedule auto-cancels (`cancel_reason=attached_gone`).
+
+## Listing / inspecting
+
+```bash
+npx --yes @parall/cli@latest schedules list --status active,paused
+npx --yes @parall/cli@latest schedules list --attached-to prll://tsk_xxx
+npx --yes @parall/cli@latest schedules list --target-id prll://usr_xxx
+npx --yes @parall/cli@latest schedules get prll://sch_xxx
+npx --yes @parall/cli@latest schedules runs prll://sch_xxx          # fire history
+npx --yes @parall/cli@latest schedules run prll://srn_xxx           # single run incl. fire-time snapshot
+```
+
+## Lifecycle
+
+```bash
+npx --yes @parall/cli@latest schedules update prll://sch_xxx --description "New prompt"
+npx --yes @parall/cli@latest schedules pause  prll://sch_xxx        # reversible
+npx --yes @parall/cli@latest schedules resume prll://sch_xxx        # does NOT catch up missed slots
+npx --yes @parall/cli@latest schedules cancel prll://sch_xxx        # terminal; row + runs preserved, prll://sch_ ref stays valid
+npx --yes @parall/cli@latest schedules delete prll://sch_xxx        # hard-delete; requires status=cancelled AND run_count=0. Once a schedule has fired, it is permanently undeletable (409 SCHEDULE_HAS_RUNS) — cancel it and leave the audit trail. Delete is for never-fired test/accidental schedules only.
+```
+
+`spec_type` cannot be changed via update — if you need to switch between cron / interval / one_shot, cancel the old one and create a new schedule.
+
+## Responding to schedule fires
+
+When you receive `[Event: schedule.fired]`, the platform has fired a schedule targeting you.
+
+The runtime (agent-core) has already done the heavy lifting: it fetched the schedule run and inlined the fire-time `description` (a frozen snapshot — later edits to the schedule don't change past fires) into your prompt, alongside `[Schedule: prll://sch_xxx]` and `[Run: prll://srn_xxx]` headers. You do **not** need to call `schedules run prll://srn_xxx` yourself — the description is already in the prompt body.
+
+Your job is to interpret the description and act:
+
+1. Read the description and any `prll://` refs it contains
+2. Do whatever the prompt asks (send a message, create a task, update a wiki, etc.) — there is no canonical response format
+3. Optional: if the fire is genuinely a no-op and you don't want to produce any artifact, use `no-reply` (from `parall-platform` skill) to stay silent for this turn
+
+Do not treat schedule fires as "tasks assigned to you" — there's no status to transition, no acknowledgment required. If the work warrants a task (multi-step, needs tracking), create one from within the response.
+
+**Fetching the run explicitly** (optional): `schedules run prll://srn_xxx` returns the same snapshot plus `dispatch_event_id` / `inbox_item_id` for audit. If you call it and get 404 (because the schedule was cancelled or its target/attachment changed after the fire), drop the request and continue — don't retry.
+
+CLI command results are JSON on stdout; mutation commands may emit auxiliary hints on stderr (for example, `Created: prll://sch_xxx`).

package/src/hooks.ts

@@ -3,6 +3,18 @@ import { PRLL_BEHAVIOR, PRLL_IDENTITY, PRLL_REFERENCE_GUIDE } from "@parall/agen
 import { extractAccountIdFromSessionKey } from "./session.js";
 import { clearDispatchGroupKey, getDispatchGroupKey, getDispatchMessageId, getParallAccountState, getSessionChatId } from "./runtime.js";
 
+/**
+ * Map the session's stored target ID (whatever the current dispatch routed
+ * to — chat, task, or schedule) to the `target_type` field on agent_step.
+ * Keeps tool_call / tool_result attribution correct across event types.
+ */
+function stepTargetType(targetId: string): string {
+  if (targetId.startsWith("cht_")) return "chat";
+  if (targetId.startsWith("tsk_")) return "task";
+  if (targetId.startsWith("sch_")) return "schedule";
+  return "";
+}
+
 /**
  * Resolve the ParallClient + orgId + sessionId for a hook context.
  * Returns undefined if the account/session is not active.
@@ -22,13 +34,19 @@ function resolveClientForHook(sessionKey: string | undefined) {
 
 const PRLL_CHANNEL_CONTEXT = `## Parall Channel — Message Delivery
 
-Messages from the Parall channel arrive as \`[Event: ...]\` blocks.
+Events from the Parall channel arrive as \`[Event: ...]\` blocks.
 Your text output is **not delivered to the user** — it is discarded silently.
-To reply, you **must** use the Parall CLI via the exec (Bash) tool.
+To respond, you **must** use the Parall CLI via the exec (Bash) tool.
+
+### Event types and where to reply
 
-Each event includes \`[Chat: ... (prll://cht_xxx)]\` — use that chat ID (or full URI) to reply:
+- **\`[Event: message.new]\`** — includes \`[Chat: ... (prll://cht_xxx)]\`. Reply into that chat:
 
-    npx --yes @parall/cli@latest messages send prll://cht_xxx --text "Your reply here"
+        npx --yes @parall/cli@latest messages send prll://cht_xxx --text "Your reply here"
+
+- **\`[Event: task.assigned]\` / \`[Event: task.comment.created]\`** — includes \`[Task: ... (prll://tsk_xxx)]\`. Act on the task; use task CLI subcommands (\`tasks update\`, \`tasks comment\`). See the \`parall-tasks\` skill.
+
+- **\`[Event: schedule.fired]\`** — includes \`[Schedule: prll://sch_xxx]\` + \`[Run: prll://srn_xxx]\` + optional \`[Attached: prll://...]\`. The body is the fire-time \`description\` verbatim. It is an opaque trigger — decide what to do (reply into an attached chat, create a task, update a wiki file, or do nothing) based on the description. The CLI does not have a "reply to schedule" primitive; any follow-up goes through the appropriate target (chat / task / wiki).
 
 Credentials are pre-configured in every Bash command — no setup needed.
 Load the \`parall-platform\` skill for full CLI reference.
@@ -66,7 +84,7 @@ export function registerParallHooks(api: OpenClawPluginApi) {
       try {
         const step = await resolved.client.createAgentStep(resolved.orgId, resolved.agentUserId, resolved.sessionId, {
           step_type: "tool_call",
-          target_type: resolved.chatId.startsWith("cht_") ? "chat" : resolved.chatId.startsWith("tsk_") ? "task" : "",
+          target_type: stepTargetType(resolved.chatId),
           target_id: resolved.chatId || undefined,
           content: {
             call_id: event.toolCallId,
@@ -102,7 +120,22 @@ export function registerParallHooks(api: OpenClawPluginApi) {
     injectedEnv.PRLL_AGENT_ID = state.agentUserId;
     if (state.activeSessionId) injectedEnv.PRLL_SESSION_ID = state.activeSessionId;
     if (stepId) injectedEnv.PRLL_STEP_ID = stepId;
-    if (chatId) injectedEnv.PRLL_CHAT_ID = chatId;
+    if (chatId) {
+      if (chatId.startsWith("sch_")) {
+        // Schedule-triggered dispatch: expose PRLL_SCHEDULE_ID so the agent
+        // can resolve the schedule; deliberately do NOT set PRLL_CHAT_ID,
+        // because schedule events have no chat to reply into, and leaving
+        // chatId=sch_* would mislead scripts into `messages send
+        // prll://sch_*` (a non-existent CLI path). The run snapshot is
+        // available via PRLL_TRIGGER_MESSAGE_ID (srn_*) for agents that
+        // want to re-fetch fire-time content.
+        injectedEnv.PRLL_SCHEDULE_ID = chatId;
+      } else {
+        // Chat and task dispatches continue to populate PRLL_CHAT_ID for
+        // backward compatibility with existing agent scripts.
+        injectedEnv.PRLL_CHAT_ID = chatId;
+      }
+    }
     if (triggerMsgId) injectedEnv.PRLL_TRIGGER_MESSAGE_ID = triggerMsgId;
     if (state.wikiMountRoot) injectedEnv.PRLL_WIKI_MOUNT_ROOT = state.wikiMountRoot;
 
@@ -127,7 +160,7 @@ export function registerParallHooks(api: OpenClawPluginApi) {
     try {
       await resolved.client.createAgentStep(resolved.orgId, resolved.agentUserId, resolved.sessionId, {
         step_type: "tool_result",
-        target_type: resolved.chatId.startsWith("cht_") ? "chat" : resolved.chatId.startsWith("tsk_") ? "task" : "",
+        target_type: stepTargetType(resolved.chatId),
         target_id: resolved.chatId || undefined,
         content: {
           call_id: event.toolCallId,