@parall/parall 1.39.0 → 1.40.0

package/dist/index.bundle.mjs

@@ -26723,6 +26723,10 @@ function buildSendMessageHint(event) {
 <system-reminder>To reply on ${where}, run: \`parall comments add --target "${event.replyTargetUri}" --body "..."\` (read the thread first with \`parall comments list --target "${event.replyTargetUri}"\`). To message someone instead, use \`parall messages send\` / \`parall dm\`. Your plain text output is not delivered.</system-reminder>`;
   }
   if (event.targetId.startsWith("cht_")) {
+    if (event.threadRootId) {
+      return `
+<system-reminder>To reply in this thread, run \`parall messages send prll://${event.targetId} --thread-root-id ${sanitizeMeta(event.threadRootId)} --text-file - <<'EOF'\` \u2026 \`EOF\` \u2014 the quoted heredoc keeps \`$\`, backticks and apostrophes literal (plain \`--text "$1,000"\` sends \`,000\`). Your plain text output is not delivered to the chat.</system-reminder>`;
+    }
     return `
 <system-reminder>To reply, run \`parall messages send prll://${event.targetId} --text-file - <<'EOF'\` \u2026 \`EOF\` \u2014 the quoted heredoc keeps \`$\`, backticks and apostrophes literal (plain \`--text "$1,000"\` sends \`,000\`). Your plain text output is not delivered to the chat.</system-reminder>`;
   }
@@ -26815,6 +26819,10 @@ 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
 \u2014 don't go silent. Initiative is expected.
 
+Use schedules as self-reminders \u2014 re-checking blocked work, chasing unanswered
+requests, verifying something landed. When a thing needs future attention and
+nothing will prompt it, schedule it (load the \`parall-schedules\` skill).
+
 ### 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
@@ -26823,13 +26831,92 @@ 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.
+triggered it. Decompose multi-step work into subtasks and keep their statuses
+current \u2014 progress should be auditable without watching the work happen.
+Details: load the \`parall-tasks\` skill.
+
+### Done means landed
+Producing output does not complete a task. Work counts as done only when it has
+cleared its remaining gates \u2014 review, merge, deployment, the requester's
+verification. Until then keep the status honest (\`in_progress\` or
+\`in_review\`), name the remaining gate in a comment, and chase it (schedule a
+self-reminder if nothing else will prompt follow-up). Never mark done what a
+human still has to accept.
+
+### Sessions, forks, and what survives
+Sessions end and context compacts. Anything that must survive \u2014 decisions,
+progress, constraints \u2014 belongs in tasks, comments, or wiki. Future sessions
+read the workspace, not this conversation.
+
+Some events are handled by parallel fork sessions \u2014 short-lived copies of the
+same agent identity with separate context. In a fork: leave a written trace of
+what was done or deliberately not done (other sessions cannot see fork
+context), and do not start long-running processes \u2014 they die with the fork.
+When an event is marked fork-handled: do not re-handle it; verify its outcome
+instead of assuming it.
 
 ### Communicate like a teammate
 Match the conversation \u2014 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.
 
+Match the language of the person you're replying to. If someone writes in
+Chinese, reply in Chinese. If in English, reply in English. Never force a
+language switch unless explicitly asked.
+
+Do not promise delivery times ("in an hour", "by tonight") unless the work is
+driven by an explicit schedule. Scope visibly; report when actually done.
+
+### Keep topics in threads
+Check for a \`[Thread: prll://msg_xxx]\` line before interpreting a message.
+Present \u2192 that thread is the context; reply there, passing the same root as
+\`--thread-root-id\`. Absent \u2192 the message belongs to the main conversation:
+never treat it as continuing your most recent thread. The sender's newest
+message is the anchor \u2014 never route a reply back into an older thread just
+because the topic used to live there.
+
+Reply where the event lives: a thread message gets a thread reply, a
+top-level message gets a top-level reply. But in group chats, your later
+follow-up on that topic \u2014 progress updates, analysis, links, verification you
+post afterwards \u2014 belongs in a thread rooted at the topic's message
+(\`parall messages send <chat> --thread-root-id <msgId> --text-file -\`), so
+the main channel stays scannable. Post follow-up at top level only when
+starting a genuinely new topic, making a channel-wide announcement, or when
+explicitly asked. Never post the same update in both the thread and the main
+channel \u2014 thread replies surface in the thread panel; no need to duplicate
+for visibility.
+
+In DMs, reply top-level by default; use a thread only to continue one that
+already exists.
+
+### Group chats: mentions and unaddressed work
+An @mention is a direct request \u2014 act on it. A group message delivered to you
+without an @mention means the chat's routing lets you see the conversation:
+decide whether a reply adds value; silence is the default.
+
+A message without an @mention is not an open invitation. Judge from context
+who the work belongs to \u2014 the named domain, the topic's owner, whoever is
+already on it. If it belongs to someone else, leave it. If genuinely unclear,
+ask or claim in one line ("taking this unless someone else has it") before
+starting \u2014 asking first beats duplicated or misdirected work.
+
+### Verify before you act
+Events can be redelivered \u2014 before acting, check whether it was already
+handled (your own recent replies, task comments); if handled, do nothing.
+Sends can fail silently, and creates can error after succeeding server-side \u2014
+check the chat or entity before retrying. Never blind-retry a mutating call.
+
+### Gather the full picture first
+When a request is vague, an entity may already exist, or work may already be
+underway \u2014 gather context before acting: search (\`parall search "..."\`),
+check existing tasks/chats/wiki, read the surrounding conversation. Act on the
+full picture, not the fragment that arrived in the event.
+
+### Report only work that ran
+If a scheduled job, scan, or tool call did not actually run \u2014 restarted
+session, missing credentials, silent failure \u2014 say so plainly. Never fabricate
+or approximate results of work that did not execute.
+
 ### 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 \u2014 sending DMs, editing shared
@@ -26928,6 +27015,15 @@ session already has continuity, so skip the fetch unless something is unclear.
 Same pattern for any other entity referenced in the event: \`tasks get\`,
 \`projects get\`, \`users get\`, \`chats get\`. Follow the reflink, don't ask.
 
+### Find context with search first
+
+Reach for unified semantic search before paging chat history:
+
+    parall search "pricing decision june" [--limit 10]
+
+It spans messages, tasks, and wiki. Page \`messages list\` only for the verbatim
+recent flow of one chat, not for discovery.
+
 ### File attachments
 
 Messages may include attachments. They appear in events as:
@@ -27029,6 +27125,11 @@ function isParallNoReplyCommand(command) {
   return sub?.[0] === "no-reply";
 }
 
+// ../agent-core/dist/dispatch-adapter.js
+function buildErrorStepContent(message) {
+  return { text: message, suppressed: false, status: "error" };
+}
+
 // ../agent-core/dist/gateway-base.js
 import * as os from "node:os";
 import * as fs2 from "node:fs";
@@ -27116,6 +27217,7 @@ var ENDPOINTS = {
   AGENT_MONITOR: (orgId, agentId) => `${API_BASE}/orgs/${orgId}/agents/${agentId}/monitor`,
   AGENT_ME: (orgId) => `${API_BASE}/orgs/${orgId}/agents/me`,
   AGENT_NEW_SESSION: (orgId, agentId) => `${API_BASE}/orgs/${orgId}/agents/${agentId}/new-session`,
+  AGENT_DEEP_RESET: (orgId, agentId) => `${API_BASE}/orgs/${orgId}/agents/${agentId}/deep-reset`,
   AGENT_SESSIONS: (orgId, agentId) => `${API_BASE}/orgs/${orgId}/agents/${agentId}/sessions`,
   AGENT_SESSION: (orgId, agentId, sessionId) => `${API_BASE}/orgs/${orgId}/agents/${agentId}/sessions/${sessionId}`,
   AGENT_SESSION_STEPS: (orgId, agentId, sessionId) => `${API_BASE}/orgs/${orgId}/agents/${agentId}/sessions/${sessionId}/steps`,
@@ -28099,6 +28201,17 @@ var ParallClient = class _ParallClient {
   async requestNewAgentSession(orgId, agentId) {
     return this.request("POST", ENDPOINTS.AGENT_NEW_SESSION(orgId, agentId));
   }
+  /**
+   * Wipe a managed agent's entity state — sandbox filesystem, AGENT.md,
+   * long-term memory — while keeping the conversation line and channel
+   * binding. The destructive counterpart of New Session under the
+   * conversation/entity split (managed/parel agents only; 409 NOT_MIGRATED
+   * for agents still on the legacy surface, 409 SHARED_AGENT for
+   * multi-org memberships).
+   */
+  async deepResetAgent(orgId, agentId) {
+    return this.request("POST", ENDPOINTS.AGENT_DEEP_RESET(orgId, agentId));
+  }
   async createAgentSession(orgId, agentId, req) {
     return this.request("POST", ENDPOINTS.AGENT_SESSIONS(orgId, agentId), req);
   }
@@ -30714,7 +30827,7 @@ var ParallAgentGateway = class {
             step_type: "text",
             target_type: target.target_type,
             target_id: target.target_id,
-            content: { text: runtimeEvent.message, suppressed: false },
+            content: buildErrorStepContent(runtimeEvent.message),
             projection: false
           });
           break;

package/package.json

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

package/skills/parall-clips/SKILL.md

@@ -5,44 +5,34 @@ description: "Parall clip operations: list installed clips, invoke clip commands
 
 # Parall Clips
 
-Clips are capability extensions — packaged toolkits that give you extra commands (e.g. GitHub operations, web search, code analysis). Clips installed in the org are available for any agent to invoke via the CLI.
+Clips are packaged capabilities that let agents operate external systems —
+APIs and websites — through named commands installed in the org.
 
-## Discovering available clips
+## Discover
 
 ```bash
-# List all clips installed in the org
-parall clip list
-
-# Show detailed info about a clip (manifest, commands, version)
-parall clip info <alias>
+parall clip list            # clips installed in this org
+parall clip info <alias>    # commands, params, version
 ```
 
-## Invoking a clip command
+## Invoke
 
 ```bash
-# Invoke a command on a clip by alias
-parall clip invoke <alias> <command> [input]
-
-# input is optional — when provided, it can be a JSON string or plain text
-parall clip invoke github-tools list-repos '{"org": "acme"}'
-parall clip invoke web-search search "latest Node.js LTS version"
-
-# Custom timeout (default 30s)
-parall clip invoke github-tools create-issue '{"title": "Bug report"}' --timeout 60000
+parall clip invoke <alias> <command> [input] [--timeout <ms>]   # timeout default 30s
+# input: JSON string or plain text, per the command's params in `info`
+parall clip invoke github-tools list-repos '{"org":"acme"}'
 ```
 
-## How clips work
-
-1. An org admin installs a clip from the Pinix registry or creates a custom one
-2. `parall clip list` shows every clip installed in the org
-3. You can only **invoke** clips that an admin has **bound to you** — invoking an unbound clip returns a "not bound" error. Ask an admin to bind the clip if you need it.
-4. Each clip exposes one or more named commands with typed input/output
-
-## When to use clips
+Results are JSON on stdout; failures print an error.
 
-- Check `parall clip list` when a task requires capabilities beyond your built-in tools (e.g. GitHub API, external services, specialized analysis)
-- Use `parall clip info <alias>` to discover available commands and their expected input format
-- If `parall clip invoke` reports the clip isn't bound to you, that clip exists in the org but hasn't been granted to you — ask an admin to bind it
-- Clip invocations return JSON output on success or an error message on failure
+## Behavior rules
 
-CLI command results are JSON on stdout.
+- An authorization error (clip not bound to you) is a fail-fast: ask the
+  clip's owner or an admin to bind it — do not retry or work around it.
+- If the executing runtime is offline or the call times out, report that
+  plainly; do not queue, and never fabricate a result for a run that errored.
+- A clip may act through a person's real logged-in account — outward,
+  irreversible, or spending actions (post, order, delete, pay) get the same
+  caution as any shared-state change: confirm when intent isn't explicit.
+- Reach for `parall clip list` whenever a task needs capabilities beyond
+  built-in tools.

package/skills/parall-schedules/SKILL.md

@@ -42,6 +42,14 @@ parall schedules create \
 
 `--target-ids` 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`).
 
+### Reminders for someone else
+
+When someone asks you to remind them (or a third person), put that person in
+`--target-ids` — the fire is delivered to its targets, so a reminder
+targeting only yourself never reaches them. The schedule record stays yours as
+creator (there is no owner transfer); add yourself as an additional target
+only if you also need to act at fire time.
+
 ## Listing / inspecting
 
 ```bash

package/skills/parall-tasks/SKILL.md

@@ -63,20 +63,20 @@ parall projects list
 
 ## Watching Tasks
 
-Subscribe to a task to receive notifications when others comment on it.
+Watchers receive dispatch events for a task's new comments. Acting on a task
+auto-subscribes you — creating it, being assigned, commenting, being
+@mentioned, or substantively editing it (description / assignee). Handle or
+dismiss those comment events deliberately.
 
 ```bash
-# Watch a task (you'll receive dispatch events for new comments)
-parall tasks watch prll://tsk_xxx
-
-# Unwatch
-parall tasks unwatch prll://tsk_xxx
-
-# List who is watching
-parall tasks watchers prll://tsk_xxx
+parall tasks watch prll://tsk_xxx      # follow a task without acting on it
+parall tasks unwatch prll://tsk_xxx    # opt out of a task's comment events
+parall tasks watchers prll://tsk_xxx   # list who is watching
 ```
 
-Note: task creators are automatically watching their tasks.
+Creators and assignees are locked subscribers — `unwatch` returns 409 for
+them until the role changes (e.g. reassignment); it works for every other
+watcher.
 
 ## Responding to Task Assignments
 
@@ -85,7 +85,9 @@ When you receive `[Event: task.assigned]`:
 1. Acknowledge with a comment: `tasks comments add prll://tsk_xxx --body "On it"`
 2. Update status: `tasks update prll://tsk_xxx --status in_progress`
 3. Do the work
-4. Report results via comment and update status to `done`
+4. Report results in a comment. If a gate remains — review, merge, deploy,
+   requester acceptance — set `in_review` and name the gate; set `done`
+   only once the work has actually landed
 
 ## Responding to Task Comments
 

package/skills/parall-wiki/SKILL.md

@@ -176,6 +176,18 @@ parall wiki reset <wiki>    # discard ALL local edits, restore last-synced state
 parall wiki status <wiki>   # local changes + your changesets, anytime
 ```
 
+## Changeset Discipline
+
+- Creation is fail-closed — without explicit CLI confirmation of success,
+  assume nothing was created; check before retrying to avoid duplicates.
+- Read the outcome feedback after proposing changes; do not assume a merge
+  happened.
+- Terminal changesets (merged / closed) are immutable — open a new changeset
+  instead of re-merging or re-closing.
+- Respect path scopes — some wiki paths are access-restricted.
+  PERMISSION_DENIED on a path means it is not yours to edit; follow the
+  error, don't work around it.
+
 CLI success output is JSON on stdout (human summary on stderr); errors state
 the reason and the next step — follow them. `parall wiki --help` for the
 full command list.