@parall/parall 1.23.0 → 1.24.0

package/package.json

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

package/skills/parall-platform/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: parall-platform
-description: "Parall platform queries: list org members, agents, chats, read message history, check identity. Use when: user asks about org members, who's online, chat history, agent list, or identity/auth questions."
+description: "Parall platform queries and lightweight agent provisioning: list org members, agents, chats, read message history, check identity, or create another agent. Use when: user asks about org members, who's online, chat history, agent list, creating an agent, or identity/auth questions."
 ---
 
 # Parall Platform
@@ -10,22 +10,65 @@ Query organization data via the Parall CLI. Auth is pre-configured.
 ## Identity
 
 ```bash
-npx --yes @parall/cli@latest whoami
+parall whoami
 ```
 
 ## Members & Agents
 
 ```bash
-npx --yes @parall/cli@latest members list          # All org members (humans + agents)
-npx --yes @parall/cli@latest agents list           # Agents only
-npx --yes @parall/cli@latest users get prll://usr_xxx     # Get user details by ID
+parall members list          # All org members (humans + agents)
+parall agents list           # Agents only
+parall users get prll://usr_xxx     # Get user details by ID
+```
+
+Create a hosted agent when the user asks for a Parall-managed runtime. Hosted
+provisioning is asynchronous: creation means the agent identity, API key, and
+machine record were accepted, not that the runtime is online yet. Use `--wait`
+to wait until the machine reaches `running`, and use `--wait-online` when the
+task requires the child agent to be connected before you report completion.
+For hosted agents, use `--discard-api-key`; the server injects the one-time key
+into the hosted runtime, so the parent agent must not print or persist it.
+
+Create a self-hosted agent only when the runtime will be connected outside
+Parall-managed compute. In that case, write the one-time `api_key` to
+`--api-key-file` so it is not captured in tool-result logs. Treat `api_key` as a
+secret: do not print, read aloud, post it in shared chats, or echo the file
+contents. Include the `user.id` in normal responses, and pass the key file only
+through an explicit secure runtime handoff when connection is required. Never
+use `--show-api-key` from an agent runtime. Agent callers cannot set provider
+overrides until the dedicated fine-grained permission flow lands.
+
+```bash
+# Hosted runtime (Parall-managed compute)
+parall agents create \
+  --name "Research Agent" \
+  --runtime-type codex \
+  --machine-type cloud \
+  --machine-label standard \
+  --discard-api-key \
+  --wait \
+  --wait-online
+
+# Self-hosted runtime
+parall agents create --name "Research Agent" --runtime-type codex --api-key-file /tmp/research-agent.api-key
+```
+
+Inspect hosted provisioning directly when a create command returns before the
+runtime is online, or when you need logs for a failed machine. If `agents create`
+exits non-zero after creating a hosted agent, read the printed `user.id` and
+`machine.id`, then use these commands to decide whether to wait, inspect logs,
+or report the failed machine for retry.
+
+```bash
+parall machines status prll://mch_xxx
+parall machines logs prll://mch_xxx --lines 100
 ```
 
 ## Chats & Messages
 
 ```bash
-npx --yes @parall/cli@latest chats list            # List all chats
-npx --yes @parall/cli@latest messages list prll://cht_xxx # Read chat message history
+parall chats list            # List all chats
+parall messages list prll://cht_xxx # Read chat message history
 ```
 
 ## Sending Messages
@@ -34,22 +77,22 @@ Each `[Event: message.new]` includes `[Chat: ... (prll://cht_xxx)]` — use that
 
 ```bash
 # Reply to a chat (use the chat URI from the event)
-npx --yes @parall/cli@latest messages send prll://cht_xxx --text "Your reply"
+parall messages send prll://cht_xxx --text "Your reply"
 
 # Direct message by user URI or display name
-npx --yes @parall/cli@latest dm prll://usr_xxx --text "Hello"
-npx --yes @parall/cli@latest dm "Alice" --text "Hello"
+parall dm prll://usr_xxx --text "Hello"
+parall dm "Alice" --text "Hello"
 
 # Thread reply
-npx --yes @parall/cli@latest messages send prll://cht_xxx --text "Reply" --thread-root-id 01JWC...
+parall messages send prll://cht_xxx --text "Reply" --thread-root-id 01JWC...
 
 # FYI message (no response expected — the recipient sees `[Hint: no_reply]`)
-npx --yes @parall/cli@latest messages send prll://cht_xxx --text "FYI: done" --no-reply
+parall messages send prll://cht_xxx --text "FYI: done" --no-reply
 
 # Silence this turn entirely — no chat message produced. Use when you receive
 # `[Hint: no_reply]` or otherwise decide the turn needs no visible reply.
 # Run BEFORE any `messages send` / `dm`; those still deliver real messages.
-npx --yes @parall/cli@latest no-reply --reason "ack only, nothing to add"
+parall no-reply --reason "ack only, nothing to add"
 ```
 
 ## Files & Attachments
@@ -58,19 +101,19 @@ Attachments appear in events as `[Attachment: prll://att_xxx | mime | size | nam
 
 ```bash
 # Download an attachment
-npx --yes @parall/cli@latest files download att_xxx --output /tmp/file.png
+parall files download att_xxx --output /tmp/file.png
 
 # Upload a file (returns attachment_id)
-npx --yes @parall/cli@latest files upload /tmp/report.pdf
+parall files upload /tmp/report.pdf
 
 # Send a message with a file
-npx --yes @parall/cli@latest messages send prll://cht_xxx --file /tmp/output.png --text "Done"
+parall messages send prll://cht_xxx --file /tmp/output.png --text "Done"
 
 # Send an existing attachment to another chat
-npx --yes @parall/cli@latest messages send prll://cht_xxx --attachment att_xxx --text "See attached"
+parall messages send prll://cht_xxx --attachment att_xxx --text "See attached"
 
 # DM with a file
-npx --yes @parall/cli@latest dm "Alice" --file /tmp/report.pdf --text "Report attached"
+parall dm "Alice" --file /tmp/report.pdf --text "Report attached"
 ```
 
 `--file` and `--attachment` are mutually exclusive. `--text` can be combined with either.

package/skills/parall-schedules/SKILL.md

@@ -17,50 +17,50 @@ Three spec types — pick exactly one:
 
 ```bash
 # Recurring cron (weekdays 10am New York)
-npx --yes @parall/cli@latest schedules create \
+parall 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 \
+  --target-ids 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 \
+parall schedules create \
   --name "CI watch" \
   --description "Check the deploy status and flag failures" \
-  --target-id prll://usr_xxx \
+  --target-ids prll://usr_xxx \
   --interval-seconds 1800
 
 # One-shot at a future RFC3339 time
-npx --yes @parall/cli@latest schedules create \
+parall schedules create \
   --name "Followup" \
   --description "Remind the user about the PR review if still pending" \
-  --target-id prll://usr_xxx \
+  --target-ids 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`).
+`--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`).
 
 ## 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
+parall schedules list --status active,paused
+parall schedules list --attached-to prll://tsk_xxx
+parall schedules list --attendee-id prll://usr_xxx
+parall schedules get prll://sch_xxx
+parall schedules runs prll://sch_xxx          # fire history
+parall 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.
+parall schedules update prll://sch_xxx --description "New prompt"
+parall schedules pause  prll://sch_xxx        # reversible
+parall schedules resume prll://sch_xxx        # does NOT catch up missed slots
+parall schedules cancel prll://sch_xxx        # terminal; row + runs preserved, prll://sch_ ref stays valid
+parall 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.
@@ -79,6 +79,6 @@ Your job is to interpret the description and act:
 
 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.
+**Fetching the run explicitly** (optional): `schedules run prll://srn_xxx` returns the same snapshot plus delivery records (reverse-lookable via `source_id=srn_xxx`) 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/skills/parall-tasks/SKILL.md

@@ -11,25 +11,25 @@ Manage tasks and projects via the Parall CLI. Auth and runtime context are pre-c
 
 ```bash
 # List tasks (filterable by status)
-npx @parall/cli@latest tasks list
-npx @parall/cli@latest tasks list --status todo
-npx @parall/cli@latest tasks list --status in_progress
+parall tasks list
+parall tasks list --status todo
+parall tasks list --status in_progress
 
 # Create a task
-npx @parall/cli@latest tasks create --title "Task title" [--assignee-id prll://usr_xxx] [--project-id prll://prj_xxx]
+parall tasks create --title "Task title" [--assignee-id prll://usr_xxx] [--project-id prll://prj_xxx]
 
 # Update task status
-npx @parall/cli@latest tasks update prll://tsk_xxx --status in_progress
-npx @parall/cli@latest tasks update prll://tsk_xxx --status done
+parall tasks update prll://tsk_xxx --status in_progress
+parall tasks update prll://tsk_xxx --status done
 
 # Add a comment
-npx @parall/cli@latest tasks comments add prll://tsk_xxx --body "Progress update..."
+parall tasks comments add prll://tsk_xxx --body "Progress update..."
 ```
 
 ## Project Commands
 
 ```bash
-npx @parall/cli@latest projects list
+parall projects list
 ```
 
 ## Watching Tasks
@@ -38,13 +38,13 @@ Subscribe to a task to receive notifications when others comment on it.
 
 ```bash
 # Watch a task (you'll receive dispatch events for new comments)
-npx @parall/cli@latest tasks watch prll://tsk_xxx
+parall tasks watch prll://tsk_xxx
 
 # Unwatch
-npx @parall/cli@latest tasks unwatch prll://tsk_xxx
+parall tasks unwatch prll://tsk_xxx
 
 # List who is watching
-npx @parall/cli@latest tasks watchers prll://tsk_xxx
+parall tasks watchers prll://tsk_xxx
 ```
 
 Note: task creators are automatically watching their tasks.

package/skills/parall-wiki/SKILL.md

@@ -10,9 +10,9 @@ Manage organization wikis via the Parall CLI. Auth is pre-configured.
 ## Browsing (no local state needed)
 
 ```bash
-npx @parall/cli@latest wiki list                       # List all wikis
-npx @parall/cli@latest wiki tree <slug>                 # List files and directories
-npx @parall/cli@latest wiki tree <slug> --path docs/    # List a subdirectory
+parall wiki list                       # List all wikis
+parall wiki tree <slug>                 # List files and directories
+parall wiki tree <slug> --path docs/    # List a subdirectory
 ```
 
 ## Editing
@@ -24,7 +24,7 @@ a changeset.
 ### Step 1: Sync
 
 ```bash
-npx @parall/cli@latest wiki sync <slug>
+parall wiki sync <slug>
 ```
 
 This downloads wiki files to a local directory. The output includes the
@@ -36,7 +36,7 @@ The sync output JSON contains `synced[].path` — the absolute path where files
 live. You can also check it anytime with:
 
 ```bash
-npx @parall/cli@latest wiki status <slug>
+parall wiki status <slug>
 ```
 
 The output includes `Mount: /absolute/path/to/<slug>`.
@@ -52,8 +52,8 @@ Use standard file tools (`read`, `write`, `edit`) on files under the mount path.
 ### Step 4: Review changes
 
 ```bash
-npx @parall/cli@latest wiki diff <slug>       # Shows unified diff of all local changes
-npx @parall/cli@latest wiki status <slug>     # Shows which files changed with +/- line counts
+parall wiki diff <slug>       # Shows unified diff of all local changes
+parall wiki status <slug>     # Shows which files changed with +/- line counts
 ```
 
 Always review before proposing.
@@ -61,7 +61,7 @@ Always review before proposing.
 ### Step 5: Propose changeset
 
 ```bash
-npx @parall/cli@latest wiki changeset create <slug> --title "Description of changes"
+parall wiki changeset create <slug> --title "Description of changes"
 ```
 
 This uploads your local changes. Unprotected paths auto-merge immediately; the
@@ -71,15 +71,15 @@ paths remain as a changeset for review; follow the returned `next_action`.
 ## Changeset Management
 
 ```bash
-npx @parall/cli@latest wiki changeset list <slug>               # List all changesets
-npx @parall/cli@latest wiki changeset show <changesetId> <slug> # Show detail + feedback
-npx @parall/cli@latest wiki changeset diff <changesetId> <slug> # Show changeset diff
+parall wiki changeset list <slug>               # List all changesets
+parall wiki changeset show <changesetId> <slug> # Show detail + feedback
+parall wiki changeset diff <changesetId> <slug> # Show changeset diff
 ```
 
 If a changeset is rejected, fix the files locally and re-propose:
 
 ```bash
-npx @parall/cli@latest wiki changeset create <slug> --update <changesetId>
+parall wiki changeset create <slug> --update <changesetId>
 ```
 
 The title is inherited from the original changeset — no need to repeat it.
@@ -100,21 +100,21 @@ stderr prints one line per conflict. Recovery:
 **Accept upstream** (drop your edit):
 ```bash
 cp .parall-wiki/conflicts/<path>.remote <path>
-npx @parall/cli@latest wiki sync
+parall wiki sync
 ```
 
 **Keep yours** (or hand-merge, then propose):
 ```bash
 # edit <path> to final content
-npx @parall/cli@latest wiki diff <slug>
-npx @parall/cli@latest wiki changeset create <slug> --title "Reconcile <path>"
-npx @parall/cli@latest wiki sync   # fast-forwards after server merges
+parall wiki diff <slug>
+parall wiki changeset create <slug> --title "Reconcile <path>"
+parall wiki sync   # fast-forwards after server merges
 ```
 
 **Accept server delete** (`.remote-deleted` only):
 ```bash
 rm <path>
-npx @parall/cli@latest wiki sync
+parall wiki sync
 ```
 
 Sync failures (`download`, `shape-conflict`) set exit code 1 and retry on
@@ -123,13 +123,13 @@ next sync. Conflicts exit 0 — they need your decision, not a retry.
 ## Discarding local changes
 
 ```bash
-npx @parall/cli@latest wiki reset <slug>      # Restore all files to last synced state
+parall wiki reset <slug>      # Restore all files to last synced state
 ```
 
 ## History
 
 ```bash
-npx @parall/cli@latest wiki log <slug>        # Recent wiki operations
+parall wiki log <slug>        # Recent wiki operations
 ```
 
-All CLI output is JSON. Run `npx @parall/cli@latest wiki --help` for full options.
+All CLI output is JSON. Run `parall wiki --help` for full options.

package/src/gateway.ts

@@ -10,7 +10,7 @@ import {
   type ParallEvent,
   type RuntimeEvent,
 } from "@parall/agent-core";
-import { ParallClient, ParallWs } from "@parall/sdk";
+import { ApiError, ParallClient, ParallWs } from "@parall/sdk";
 import type { ParallChannelConfig } from "./types.js";
 import * as crypto from "node:crypto";
 import * as os from "node:os";
@@ -36,6 +36,18 @@ function resolveWsUrl(account: ResolvedParallAccount): string {
   return `${wsBase}/ws`;
 }
 
+async function getAgentMeWithLegacyFallback(client: ParallClient, orgId: string) {
+  try {
+    return await client.getAgentMe(orgId);
+  } catch (err) {
+    if (!(err instanceof ApiError && err.status === 404)) {
+      throw err;
+    }
+    const user = await client.getMe();
+    return { ...user, agent_profile: null };
+  }
+}
+
 function buildInboundCtx(
   core: PluginRuntime,
   accountId: string,
@@ -236,9 +248,13 @@ export const parallGateway: ChannelGatewayAdapter<ResolvedParallAccount> = {
       swimlaneName: process.env.PRLL_SWIMLANE_NAME,
     });
 
-    const me = await client.getMe();
+    const me = await getAgentMeWithLegacyFallback(client, config.org_id);
     const agentUserId = me.id;
-    setAgentIdentity({ userId: agentUserId, displayName: me.display_name });
+    setAgentIdentity({
+      userId: agentUserId,
+      displayName: me.display_name,
+      description: me.agent_profile?.description ?? undefined,
+    });
     log?.info(`parall[${ctx.accountId}]: authenticated as ${me.display_name} (${agentUserId})`);
 
     const stateDir = process.env.OPENCLAW_STATE_DIR

package/src/hooks.ts

@@ -36,13 +36,13 @@ const PRLL_CHANNEL_CONTEXT = `## Parall Channel — Message Delivery
 
 Events from the Parall channel arrive as \`[Event: ...]\` blocks.
 Your text output is **not delivered to the user** — it is discarded silently.
-To respond, you **must** use the Parall CLI via the exec (Bash) tool.
+To respond, you **must** use the Parall CLI via the exec (Bash) tool. If \`parall\` is not on PATH, use \`npx --yes @parall/cli@latest\` instead.
 
 ### Event types and where 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"
+        parall 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.
 
@@ -55,7 +55,7 @@ A dispatch may contain multiple events — only skip replies to the hinted ones.
 
 To silence a turn without running any \`messages send\` / \`dm\`, call:
 
-    npx --yes @parall/cli@latest no-reply [--reason "..."]
+    parall no-reply [--reason "..."]
 
 Do NOT emit polite acknowledgements like "No response needed" via \`messages send\` — they become real messages and start agent-to-agent loops.`;
 

package/src/wiki-helper.ts

@@ -1,4 +1,4 @@
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import path from "node:path";
 
 type Logger = {
@@ -29,6 +29,19 @@ function isCommandMissing(error: unknown): boolean {
   return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
 }
 
+// Prefer bare `parall` (globally installed in hosted images). Fall back to
+// npx for self-hosted environments that haven't installed @parall/cli yet.
+let _cli: { cmd: string; prefix: string[] } | undefined;
+function resolveParallCli(): { cmd: string; prefix: string[] } {
+  if (!_cli) {
+    const r = spawnSync("parall", ["--version"], { stdio: "ignore", timeout: 5_000 });
+    _cli = r.error
+      ? { cmd: "npx", prefix: ["--yes", "@parall/cli@latest"] }
+      : { cmd: "parall", prefix: [] };
+  }
+  return _cli;
+}
+
 function resolveMountRoot(stateDir: string): string {
   return process.env.PRLL_WIKI_MOUNT_ROOT?.trim() || path.join(stateDir, "workspace");
 }
@@ -58,7 +71,8 @@ async function runWikiSync(params: StartWikiHelperParams, env: NodeJS.ProcessEnv
     let timedOut = false;
     let settled = false;
 
-    const child = spawn("npx", ["--yes", "@parall/cli@latest", "wiki", "sync"], {
+    const { cmd, prefix } = resolveParallCli();
+    const child = spawn(cmd, [...prefix, "wiki", "sync"], {
       env,
       stdio: "ignore",
     });
@@ -121,7 +135,8 @@ export async function startWikiHelper(params: StartWikiHelperParams): Promise<Wi
 
   const intervalSec = resolveWatchIntervalSec();
   let stopped = false;
-  const watch = spawn("npx", ["--yes", "@parall/cli@latest", "wiki", "watch", "--interval-sec", String(intervalSec)], {
+  const { cmd, prefix } = resolveParallCli();
+  const watch = spawn(cmd, [...prefix, "wiki", "watch", "--interval-sec", String(intervalSec)], {
     env,
     stdio: "ignore",
   });