@parall/agent-core 1.47.0 → 1.48.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/agent-core",
-  "version": "1.47.0",
+  "version": "1.48.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.48.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.