@parall/agent-core 1.47.0 → 1.49.0

package/dist/skills/parall-clips.d.ts

@@ -1,2 +1,2 @@
-export declare const PARALL_CLIPS_SKILL = "# Parall Clips\n\nClips are packaged capabilities that let agents operate external systems \u2014\nAPIs and websites \u2014 through named commands installed in the org.\n\n## Discover\n\n```bash\nparall clip list            # clips installed in this org\nparall clip info <alias>    # commands, params, version\n```\n\n## Invoke\n\n```bash\nparall clip invoke <alias> <command> [input] [--timeout <ms>]   # timeout default 30s\n# input: JSON string or plain text, per the command's params in `info`\nparall clip invoke github-tools list-repos '{\"org\":\"acme\"}'\n```\n\nResults are JSON on stdout; failures print an error.\n\n## Behavior rules\n\n- An authorization error (clip not bound to you) is a fail-fast: ask the\n  clip's owner or an admin to bind it \u2014 do not retry or work around it.\n- If the executing runtime is offline or the call times out, report that\n  plainly; do not queue, and never fabricate a result for a run that errored.\n- Hosted browser activation is handled by the CLI: it waits (bounded) while a\n  cold hosted browser starts, so if the invoke still fails, report the error \u2014\n  do not blind-retry in a loop.\n- A clip may act through a person's real logged-in account \u2014 outward,\n  irreversible, or spending actions (post, order, delete, pay) get the same\n  caution as any shared-state change: confirm when intent isn't explicit.\n- Reach for `parall clip list` whenever a task needs capabilities beyond\n  built-in tools.\n";
+export declare const PARALL_CLIPS_SKILL = "# Parall Clips\n\nClips are packaged capabilities that let agents operate external systems \u2014\nAPIs and websites \u2014 through named commands installed in the org.\n\n## Discover\n\n```bash\nparall clip list            # clips installed in this org\nparall clip info <alias>    # commands, params, version\n```\n\n## Invoke\n\n```bash\nparall clip invoke <alias> <command> [input] [--timeout <ms>]   # timeout default 30s\n# input: JSON string or plain text, per the command's params in `info`\nparall clip invoke github-tools list-repos '{\"org\":\"acme\"}'\n```\n\nResults are JSON on stdout; failures print an error.\n\n## Execute on an Edge device (registry clips)\n\nRegistry clips run on an Edge \u2014 a member's desktop, or an org-shared cloud\nprofile. **Name the target explicitly.** A cloud profile has NO implicit\nroute; omitting the target entirely is a desktop-only legacy form that\nreaches just YOUR OWN online desktop device \u2014 never a shared cloud profile.\n\n```bash\nparall clip exec <clip> <command> [args] --connection <id|alias>  # the normal form\nparall clip exec browser-tools screenshot '{\"url\":\"\u2026\"}' --connection cloud-main\n```\n\n- A cloud (hosted) profile is reachable ONLY via `--connection` \u2014 the clip\n  connection its maintainer bound (`ccn_\u2026` id or alias). That binding IS your\n  authorization; without one the server answers `HOSTED_CONNECTION_REQUIRED`\n  and the fix is to ask an owner/admin to bind the clip, never to retry.\n- `--edge <edgeId>` targets only a desktop device YOU own.\n- Cold cloud profiles are handled by the CLI: it absorbs `EDGE_ACTIVATING`\n  with a bounded wait (~60s) while the profile starts. If the command still\n  fails, report the error \u2014 do not blind-retry in a loop.\n\n## Behavior rules\n\n- An authorization error (clip not bound to you) is a fail-fast: ask the\n  clip's owner or an admin to bind it \u2014 do not retry or work around it.\n- If the executing runtime is offline or the call times out, report that\n  plainly; do not queue, and never fabricate a result for a run that errored.\n- Hosted browser activation is handled by the CLI: it waits (bounded) while a\n  cold hosted browser starts, so if the invoke still fails, report the error \u2014\n  do not blind-retry in a loop.\n- **`OUTCOME_UNKNOWN` is never retryable.** It means the command was\n  dispatched and MAY HAVE EXECUTED even though no result came back. Retrying\n  could post, order or delete twice. Verify the effect through the system you\n  acted on (or tell the human, quoting the request id from the error) before\n  ever re-running. `EDGE_BUSY` is the opposite: guaranteed-unexecuted \u2014 wait\n  briefly, then one retry is safe.\n- A clip may act through a person's real logged-in account \u2014 outward,\n  irreversible, or spending actions (post, order, delete, pay) get the same\n  caution as any shared-state change: confirm when intent isn't explicit.\n- Reach for `parall clip list` whenever a task needs capabilities beyond\n  built-in tools.\n";
 //# sourceMappingURL=parall-clips.d.ts.map

package/dist/skills/parall-clips.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parall-clips.d.ts","sourceRoot":"","sources":["../../src/skills/parall-clips.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,q8CAoC9B,CAAC"}
+{"version":3,"file":"parall-clips.d.ts","sourceRoot":"","sources":["../../src/skills/parall-clips.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,w+FA+D9B,CAAC"}

package/dist/skills/parall-clips.js

@@ -20,6 +20,27 @@ parall clip invoke github-tools list-repos '{"org":"acme"}'
 
 Results are JSON on stdout; failures print an error.
 
+## Execute on an Edge device (registry clips)
+
+Registry clips run on an Edge — a member's desktop, or an org-shared cloud
+profile. **Name the target explicitly.** A cloud profile has NO implicit
+route; omitting the target entirely is a desktop-only legacy form that
+reaches just YOUR OWN online desktop device — never a shared cloud profile.
+
+\`\`\`bash
+parall clip exec <clip> <command> [args] --connection <id|alias>  # the normal form
+parall clip exec browser-tools screenshot '{"url":"…"}' --connection cloud-main
+\`\`\`
+
+- A cloud (hosted) profile is reachable ONLY via \`--connection\` — the clip
+  connection its maintainer bound (\`ccn_…\` id or alias). That binding IS your
+  authorization; without one the server answers \`HOSTED_CONNECTION_REQUIRED\`
+  and the fix is to ask an owner/admin to bind the clip, never to retry.
+- \`--edge <edgeId>\` targets only a desktop device YOU own.
+- Cold cloud profiles are handled by the CLI: it absorbs \`EDGE_ACTIVATING\`
+  with a bounded wait (~60s) while the profile starts. If the command still
+  fails, report the error — do not blind-retry in a loop.
+
 ## Behavior rules
 
 - An authorization error (clip not bound to you) is a fail-fast: ask the
@@ -29,6 +50,12 @@ Results are JSON on stdout; failures print an error.
 - Hosted browser activation is handled by the CLI: it waits (bounded) while a
   cold hosted browser starts, so if the invoke still fails, report the error —
   do not blind-retry in a loop.
+- **\`OUTCOME_UNKNOWN\` is never retryable.** It means the command was
+  dispatched and MAY HAVE EXECUTED even though no result came back. Retrying
+  could post, order or delete twice. Verify the effect through the system you
+  acted on (or tell the human, quoting the request id from the error) before
+  ever re-running. \`EDGE_BUSY\` is the opposite: guaranteed-unexecuted — wait
+  briefly, then one retry is safe.
 - 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.

package/dist/skills/parall-tasks.d.ts

@@ -1,2 +1,2 @@
-export declare const PARALL_TASKS_SKILL = "# Parall Tasks\n\nManage tasks and projects via the Parall CLI. Auth and runtime context are pre-configured.\n\n## Finding What's on Someone's Plate (incl. subtasks)\n\nTo answer \"what do I still have to do\", \"what's <person> working on\", or any\n\"open work assigned to X\" question, use `tasks assigned`:\n\n```bash\n# Pending tasks (todo + in_progress) assigned to a member \u2014 INCLUDES subtasks.\nparall tasks assigned prll://usr_xxx   # a specific person (e.g. the human who asked)\nparall tasks assigned                  # yourself (defaults to the authenticated user)\n```\n\nThis is the authoritative \"open work for a person\" query. It returns every\npending task assigned to that member **including subtasks** \u2014 even when the\nsubtask's parent task belongs to someone else. Decomposed work usually lives in\nsubtasks, so do NOT answer this kind of question from `tasks list` alone:\nthat is org-wide, page-capped, and not scoped to a person, so a person's\nsubtasks are easily missed.\n\nResolve a person's `prll://usr_` id from the message context, the members\nlist, or ref search; your own id comes from `parall whoami`.\n\n## Task Commands\n\n```bash\n# List tasks (org-wide; filter by status, assignee, or parent)\nparall tasks list\nparall tasks list --status todo\nparall tasks list --status in_progress\nparall tasks list --assignee-id prll://usr_xxx   # first page only (default 20) \u2014 for a person's FULL backlog use 'tasks assigned' above\nparall tasks subtasks prll://tsk_xxx             # children of a single parent task\n\n# Create a task (add --parent-id to make it a SUBTASK of another task)\nparall tasks create --title \"Task title\" [--assignee-id prll://usr_xxx] [--parent-id prll://tsk_xxx] [--project-id prll://prj_xxx] [--due-date 2026-08-01]\n\n# Update task status \u2014 add --placement end so the task lands at the end of\n# its NEW status column (a bare --status keeps the old column's sort_order)\nparall tasks update prll://tsk_xxx --status in_progress --placement end\nparall tasks update prll://tsk_xxx --status done --placement end\n\n# Due date \u2014 a plain YYYY-MM-DD date (no timestamps); \"none\" clears it\nparall tasks update prll://tsk_xxx --due-date 2026-08-01\nparall tasks update prll://tsk_xxx --due-date none\n\n# Move a task to the end of its status column\nparall tasks update prll://tsk_xxx --placement end\n\n# Add a comment\nparall tasks comments add prll://tsk_xxx --body \"Progress update...\"\n```\n\nOrdering: to append a task to the end of a status column, always use\n`--placement end` \u2014 the server resolves the position atomically. This\nincludes status changes: a bare `--status` keeps the task's old\n`sort_order`, which may collide inside the new column. Do NOT compute a\n`sort_order` value yourself from listed tasks (your view may be stale or\npartial). `--sort-order` is only for pinpoint insertion between two cards\nyou just listed, and it cannot be combined with `--placement`.\n\nSubtasks are just tasks with a parent: create one with `tasks create --parent-id`,\nre-parent with `tasks update --parent-id`, list a parent's children with\n`tasks subtasks`. `tasks list` without `--parent-id` already returns both\ntop-level tasks and subtasks; per-person open work is best fetched with\n`tasks assigned` (above).\n\n## Project Commands\n\n```bash\nparall projects list\n```\n\n## Watching Tasks\n\nWatchers receive dispatch events for a task's new comments. Acting on a task\nauto-subscribes you \u2014 creating it, being assigned, commenting, being\n@mentioned, or substantively editing it (description / assignee). Handle or\ndismiss those comment events deliberately.\n\n```bash\nparall tasks watch prll://tsk_xxx      # follow a task without acting on it\nparall tasks unwatch prll://tsk_xxx    # opt out of a task's comment events\nparall tasks watchers prll://tsk_xxx   # list who is watching\n```\n\nCreators and assignees are locked subscribers \u2014 `unwatch` returns 409 for\nthem until the role changes (e.g. reassignment); it works for every other\nwatcher.\n\n## Responding to Task Assignments\n\nWhen you receive `[Event: task.assigned]`:\n\n1. Acknowledge with a comment: `tasks comments add prll://tsk_xxx --body \"On it\"`\n2. Update status: `tasks update prll://tsk_xxx --status in_progress --placement end`\n3. Do the work\n4. Report results in a comment. If a gate remains \u2014 review, merge, deploy,\n   requester acceptance \u2014 set `in_review` and name the gate; set `done`\n   only once the work has actually landed\n\n## Responding to Task Comments\n\nWhen you receive `[Event: task.comment.created]`, someone commented on a task you are watching. Read the comment body and respond if action is needed:\n\n1. Review the comment content and task context\n2. Reply via comment: `tasks comments add prll://tsk_xxx --body \"Response...\"`\n3. If the comment requests status changes, update accordingly\n\nCLI success output is JSON; errors print a JSON line plus, on a `PERMISSION_DENIED`, an optional plain-text `Request approval:` line \u2014 read both.\n";
+export declare const PARALL_TASKS_SKILL = "# Parall Tasks\n\nManage tasks and projects via the Parall CLI. Auth and runtime context are pre-configured.\n\n## Finding What's on Someone's Plate (incl. subtasks)\n\nTo answer \"what do I still have to do\", \"what's <person> working on\", or any\n\"open work assigned to X\" question, use `tasks assigned`:\n\n```bash\n# Pending tasks (todo + in_progress) assigned to a member \u2014 INCLUDES subtasks.\nparall tasks assigned prll://usr_xxx   # a specific person (e.g. the human who asked)\nparall tasks assigned                  # yourself (defaults to the authenticated user)\n```\n\nThis is the authoritative \"open work for a person\" query. It returns every\npending task assigned to that member **including subtasks** \u2014 even when the\nsubtask's parent task belongs to someone else. Decomposed work usually lives in\nsubtasks, so do NOT answer this kind of question from `tasks list` alone:\nthat is org-wide, page-capped, and not scoped to a person, so a person's\nsubtasks are easily missed.\n\nResolve a person's `prll://usr_` id from the message context, the members\nlist, or ref search; your own id comes from `parall whoami`.\n\n## Task Commands\n\n```bash\n# List tasks (org-wide; filter by status, assignee, or parent)\nparall tasks list\nparall tasks list --status todo\nparall tasks list --status in_progress\nparall tasks list --assignee-id prll://usr_xxx   # first page only (default 20) \u2014 for a person's FULL backlog use 'tasks assigned' above\nparall tasks subtasks prll://tsk_xxx             # children of a single parent task\n\n# Create a task (add --parent-id to make it a SUBTASK of another task)\nparall tasks create --title \"Task title\" [--assignee-id prll://usr_xxx] [--parent-id prll://tsk_xxx] [--project-id prll://prj_xxx] [--planned-start 2026-07-20] [--due-date 2026-08-01]\n\n# Update task status \u2014 add --placement end so the task lands at the end of\n# its NEW status column (a bare --status keeps the old column's sort_order)\nparall tasks update prll://tsk_xxx --status in_progress --placement end\nparall tasks update prll://tsk_xxx --status done --placement end\n\n# Due date \u2014 a plain YYYY-MM-DD date (no timestamps); \"none\" clears it\nparall tasks update prll://tsk_xxx --due-date 2026-08-01\nparall tasks update prll://tsk_xxx --due-date none\n\n# Planned start \u2014 same grammar as --due-date; must be on or before the due\n# date when both are set. This is the planned schedule's left-edge date,\n# NOT when work actually began (that stays on lifecycle timestamps)\nparall tasks update prll://tsk_xxx --planned-start 2026-07-20\nparall tasks update prll://tsk_xxx --planned-start none\n\n# Move a task to the end of its status column\nparall tasks update prll://tsk_xxx --placement end\n\n# Add a comment\nparall tasks comments add prll://tsk_xxx --body \"Progress update...\"\n```\n\nOrdering: to append a task to the end of a status column, always use\n`--placement end` \u2014 the server resolves the position atomically. This\nincludes status changes: a bare `--status` keeps the task's old\n`sort_order`, which may collide inside the new column. Do NOT compute a\n`sort_order` value yourself from listed tasks (your view may be stale or\npartial). `--sort-order` is only for pinpoint insertion between two cards\nyou just listed, and it cannot be combined with `--placement`.\n\nSubtasks are just tasks with a parent: create one with `tasks create --parent-id`,\nre-parent with `tasks update --parent-id`, list a parent's children with\n`tasks subtasks`. `tasks list` without `--parent-id` already returns both\ntop-level tasks and subtasks; per-person open work is best fetched with\n`tasks assigned` (above).\n\n## Project Commands\n\n```bash\nparall projects list\n```\n\n## Watching Tasks\n\nWatchers receive dispatch events for a task's new comments. Acting on a task\nauto-subscribes you \u2014 creating it, being assigned, commenting, being\n@mentioned, or substantively editing it (description / assignee). Handle or\ndismiss those comment events deliberately.\n\n```bash\nparall tasks watch prll://tsk_xxx      # follow a task without acting on it\nparall tasks unwatch prll://tsk_xxx    # opt out of a task's comment events\nparall tasks watchers prll://tsk_xxx   # list who is watching\n```\n\nCreators and assignees are locked subscribers \u2014 `unwatch` returns 409 for\nthem until the role changes (e.g. reassignment); it works for every other\nwatcher.\n\n## Responding to Task Assignments\n\nWhen you receive `[Event: task.assigned]`:\n\n1. Acknowledge with a comment: `tasks comments add prll://tsk_xxx --body \"On it\"`\n2. Update status: `tasks update prll://tsk_xxx --status in_progress --placement end`\n3. Do the work\n4. Report results in a comment. If a gate remains \u2014 review, merge, deploy,\n   requester acceptance \u2014 set `in_review` and name the gate; set `done`\n   only once the work has actually landed\n\n## Responding to Task Comments\n\nWhen you receive `[Event: task.comment.created]`, someone commented on a task you are watching. Read the comment body and respond if action is needed:\n\n1. Review the comment content and task context\n2. Reply via comment: `tasks comments add prll://tsk_xxx --body \"Response...\"`\n3. If the comment requests status changes, update accordingly\n\nCLI success output is JSON; errors print a JSON line plus, on a `PERMISSION_DENIED`, an optional plain-text `Request approval:` line \u2014 read both.\n";
 //# sourceMappingURL=parall-tasks.d.ts.map

package/dist/skills/parall-tasks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parall-tasks.d.ts","sourceRoot":"","sources":["../../src/skills/parall-tasks.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,k+JA+G9B,CAAC"}
+{"version":3,"file":"parall-tasks.d.ts","sourceRoot":"","sources":["../../src/skills/parall-tasks.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,y1KAqH9B,CAAC"}

package/dist/skills/parall-tasks.js

@@ -34,7 +34,7 @@ parall tasks list --assignee-id prll://usr_xxx   # first page only (default 20)
 parall tasks subtasks prll://tsk_xxx             # children of a single parent task
 
 # Create a task (add --parent-id to make it a SUBTASK of another task)
-parall tasks create --title "Task title" [--assignee-id prll://usr_xxx] [--parent-id prll://tsk_xxx] [--project-id prll://prj_xxx] [--due-date 2026-08-01]
+parall tasks create --title "Task title" [--assignee-id prll://usr_xxx] [--parent-id prll://tsk_xxx] [--project-id prll://prj_xxx] [--planned-start 2026-07-20] [--due-date 2026-08-01]
 
 # Update task status — add --placement end so the task lands at the end of
 # its NEW status column (a bare --status keeps the old column's sort_order)
@@ -45,6 +45,12 @@ parall tasks update prll://tsk_xxx --status done --placement end
 parall tasks update prll://tsk_xxx --due-date 2026-08-01
 parall tasks update prll://tsk_xxx --due-date none
 
+# Planned start — same grammar as --due-date; must be on or before the due
+# date when both are set. This is the planned schedule's left-edge date,
+# NOT when work actually began (that stays on lifecycle timestamps)
+parall tasks update prll://tsk_xxx --planned-start 2026-07-20
+parall tasks update prll://tsk_xxx --planned-start none
+
 # Move a task to the end of its status column
 parall tasks update prll://tsk_xxx --placement end
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/agent-core",
-  "version": "1.47.0",
+  "version": "1.49.0",
   "description": "Shared agent runtime orchestration helpers for Parall",
   "license": "MIT",
   "repository": {
@@ -36,7 +36,7 @@
     "@opentelemetry/sdk-metrics": "^1.30.0",
     "@opentelemetry/sdk-trace-node": "^1.30.0",
     "undici": "^7.24.8",
-    "@parall/sdk": "1.47.0"
+    "@parall/sdk": "1.49.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/skills/parall-clips.ts

@@ -20,6 +20,27 @@ parall clip invoke github-tools list-repos '{"org":"acme"}'
 
 Results are JSON on stdout; failures print an error.
 
+## Execute on an Edge device (registry clips)
+
+Registry clips run on an Edge — a member's desktop, or an org-shared cloud
+profile. **Name the target explicitly.** A cloud profile has NO implicit
+route; omitting the target entirely is a desktop-only legacy form that
+reaches just YOUR OWN online desktop device — never a shared cloud profile.
+
+\`\`\`bash
+parall clip exec <clip> <command> [args] --connection <id|alias>  # the normal form
+parall clip exec browser-tools screenshot '{"url":"…"}' --connection cloud-main
+\`\`\`
+
+- A cloud (hosted) profile is reachable ONLY via \`--connection\` — the clip
+  connection its maintainer bound (\`ccn_…\` id or alias). That binding IS your
+  authorization; without one the server answers \`HOSTED_CONNECTION_REQUIRED\`
+  and the fix is to ask an owner/admin to bind the clip, never to retry.
+- \`--edge <edgeId>\` targets only a desktop device YOU own.
+- Cold cloud profiles are handled by the CLI: it absorbs \`EDGE_ACTIVATING\`
+  with a bounded wait (~60s) while the profile starts. If the command still
+  fails, report the error — do not blind-retry in a loop.
+
 ## Behavior rules
 
 - An authorization error (clip not bound to you) is a fail-fast: ask the
@@ -29,6 +50,12 @@ Results are JSON on stdout; failures print an error.
 - Hosted browser activation is handled by the CLI: it waits (bounded) while a
   cold hosted browser starts, so if the invoke still fails, report the error —
   do not blind-retry in a loop.
+- **\`OUTCOME_UNKNOWN\` is never retryable.** It means the command was
+  dispatched and MAY HAVE EXECUTED even though no result came back. Retrying
+  could post, order or delete twice. Verify the effect through the system you
+  acted on (or tell the human, quoting the request id from the error) before
+  ever re-running. \`EDGE_BUSY\` is the opposite: guaranteed-unexecuted — wait
+  briefly, then one retry is safe.
 - 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.

package/src/skills/parall-tasks.ts

@@ -34,7 +34,7 @@ parall tasks list --assignee-id prll://usr_xxx   # first page only (default 20)
 parall tasks subtasks prll://tsk_xxx             # children of a single parent task
 
 # Create a task (add --parent-id to make it a SUBTASK of another task)
-parall tasks create --title "Task title" [--assignee-id prll://usr_xxx] [--parent-id prll://tsk_xxx] [--project-id prll://prj_xxx] [--due-date 2026-08-01]
+parall tasks create --title "Task title" [--assignee-id prll://usr_xxx] [--parent-id prll://tsk_xxx] [--project-id prll://prj_xxx] [--planned-start 2026-07-20] [--due-date 2026-08-01]
 
 # Update task status — add --placement end so the task lands at the end of
 # its NEW status column (a bare --status keeps the old column's sort_order)
@@ -45,6 +45,12 @@ parall tasks update prll://tsk_xxx --status done --placement end
 parall tasks update prll://tsk_xxx --due-date 2026-08-01
 parall tasks update prll://tsk_xxx --due-date none
 
+# Planned start — same grammar as --due-date; must be on or before the due
+# date when both are set. This is the planned schedule's left-edge date,
+# NOT when work actually began (that stays on lifecycle timestamps)
+parall tasks update prll://tsk_xxx --planned-start 2026-07-20
+parall tasks update prll://tsk_xxx --planned-start none
+
 # Move a task to the end of its status column
 parall tasks update prll://tsk_xxx --placement end