@parall/parall 1.52.2 → 1.53.0

package/package.json

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

package/skills/parall-clip-authoring/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: parall-clip-authoring
+description: "Authoring a v3 registry clip: write manifest.json + command .js files + _helpers, drive the browser/tab runtime API, publish the directory to the org registry with `parall clip publish` — or declare a manifest-only MCP clip pointing at a remote tool server. Use when: user asks to write/create/build a new clip, author a clip command, package a browser automation as a clip, declare an MCP clip, or publish a clip. For CALLING clips that already exist, use parall-clips instead."
+---
+
+# Authoring a Parall Clip (v3)
+
+Write a **registry (v3) clip**. This skill is for CREATING clips; to DISCOVER
+and CALL clips that are already installed, use the Parall Clips skill instead.
+
+Two kinds of clip exist, and this document covers authoring both:
+
+- A **browser clip** — the main subject here — is a folder of named commands
+  that run on an Edge (a member's desktop or an org-shared cloud profile) and
+  drive a real browser session: one manifest (`manifest.json` or `site.json`,
+  either name works) + one `.js` file per command + optional `_`-prefixed
+  helpers. The Edge runs each command's JS in a sandbox with a browser handle
+  bound to the target profile.
+- An **MCP clip** is a manifest-ONLY declaration pointing at a remote MCP tool
+  server — no `.js` files; its tools come live from that server's own
+  `tools/list`, never from the manifest. See "MCP clips" below.
+
+## Project layout
+
+```
+my-clip/
+├── manifest.json     # name, description, version, command params
+├── _helpers.js       # OPTIONAL — any _-prefixed file is auto-injected into every command
+├── search.js         # one command = one file; filename (minus .js) IS the command name
+└── profile.js        # another command
+```
+
+## manifest.json
+
+```json
+{
+  "name": "twitter",
+  "description": "Twitter / X",
+  "version": "1.0.0",
+  "commands": {
+    "search": {
+      "description": "Search tweets",
+      "params": {
+        "query": { "type": "string", "required": true },
+        "count": { "type": "number", "required": false }
+      }
+    },
+    "profile": {
+      "description": "Fetch a user profile",
+      "params": { "handle": { "type": "string", "required": true } }
+    }
+  }
+}
+```
+
+- `commands` keys MUST match the `.js` filenames (`search` ↔ `search.js`).
+- `params` is the input contract the caller sees in `clip info`; validate them in code too.
+- **No top-level `"type"` needed for a browser clip** — omitting it means
+  browser. The only accepted values are `"browser"` and `"mcp"` (for the
+  latter, see "MCP clips" below). **`"type": "clip"` is the legacy Pinix v2
+  package value and is refused at publish** — don't copy it in from an older
+  clip.
+
+## A command file
+
+```js
+// search.js — a command is a single async function of (args).
+// The code does NOT know or pick the profile; the Edge binds it per invocation.
+//
+// SHAPE, not a runnable Twitter client: the "..." parts (the GraphQL path,
+// parseTweets' body) are what you fill in per target site. Deliberately not
+// pinned to a real X endpoint — a site's internal API paths rotate, and a
+// stale one baked into this skill would teach a URL that 404s.
+module.exports = async function (args) {
+  if (!args.query) return { error: "Missing argument: query" };
+
+  const tab = await browser.open("https://x.com");
+  // Everything after open() goes in try/finally: an early return or a thrown
+  // fetch would otherwise leak the tab, and the Edge is long-lived.
+  try {
+    const ct0 = await tab.cookie("ct0");
+    if (!ct0) return { error: "Not logged in" };
+
+    const data = await tab.fetch("/i/api/graphql/.../SearchTimeline?...", {
+      headers: twitterHeaders(ct0), // from _helpers.js, auto-injected
+    });
+    return { query: args.query, tweets: parseTweets(data) };
+  } finally {
+    await tab.close();
+  }
+};
+```
+
+Return a plain JSON-serializable object. A thrown error surfaces to the caller as
+`SCRIPT_ERROR`; a returned `{ error: "..." }` is your own typed failure — prefer it
+for expected cases (not logged in, missing arg).
+
+## Helpers (`_`-prefixed)
+
+Any file whose name starts with `_` is NOT a command. Its top-level functions are
+injected into every command's scope — no import/require needed:
+
+```js
+// _helpers.js
+function twitterHeaders(ct0) {
+  return { "X-Csrf-Token": ct0, "X-Twitter-Auth-Type": "OAuth2Session" };
+}
+function parseTweets(data) { /* ... */ }
+```
+
+## Runtime API (globals available in every command)
+
+- `browser.open(url)` → tab handle · `browser.tabs()` → open tabs
+- `tab.cookie(name)` · `tab.fetch(url, opts)` (in-browser fetch, carries the session)
+- `tab.eval(expr)` (escape hatch) · `tab.click(sel)` · `tab.fill(sel, text)` · `tab.navigate(url)`
+- `tab.waitForSelector(sel)` · `tab.getTitle()` · `tab.getURL()` · `tab.screenshot()` · `tab.close()`
+- `fetch` — runtime-side HTTP, does NOT go through the browser (no session)
+- `console` — logs · `args` — the invocation input
+
+**Prefer `tab.fetch` over `tab.eval`**: fetch reuses the logged-in session and
+returns structured data; eval is the last resort. Always `tab.close()` what you
+open, and do it in a `finally` — an early return or a thrown fetch is exactly
+when the tab leaks.
+
+## Develop → publish → iterate
+
+Use the platform `parall clip` subcommands — they reuse the credentials you
+already have (`PRLL_API_KEY` / `PRLL_ORG_ID`), so there is nothing to install
+or configure.
+
+> A separate **standalone `parall-clip`** binary also exists (the Edge-side
+> authoring tool). It takes the SAME operations but a DIFFERENT argument shape —
+> `parall-clip exec <clip> <cmd> --query "AI" --count 10` passes one flag per
+> param, while `parall clip exec` takes a single JSON blob. Do not mix the two
+> forms; everything below is the platform CLI.
+
+1. **Publish** the clip directory to the org registry. Publishing is not a
+   release step here — it is the edit loop's SAVE button, because exec only
+   ever sees published files:
+
+   ```sh
+   parall clip publish ./my-clip/
+   ```
+
+   It packages the directory (the manifest plus the directory's top-level
+   `.js` files; an MCP clip is manifest-only) and POSTs it for you (5 MB cap).
+   `name` is the org-wide upsert key — manifest fields win, else the directory
+   name / `0.0.1` / `private` fill the gaps. Re-publishing an existing name is
+   **author-only** and REPLACES the file set. Publishing into YOUR org makes it
+   usable there immediately (same-org self-reference, no review);
+   `"visibility": "public"` additionally submits the version for platform
+   review before it can spread cross-org.
+
+   Programmatic equivalent (what `publish` calls under the hood — use only if
+   you can't run the CLI). Send it verbatim-shaped: `visibility` is exactly
+   one of `"private"` / `"public"`, and `files` maps each filename to its
+   source as a string:
+
+   ```
+   POST /api/v1/orgs/{orgId}/clip-registry/publish
+   {
+     "name": "twitter",
+     "description": "Twitter / X",
+     "version": "1.0.0",
+     "visibility": "private",
+     "manifest": {
+       "name": "twitter",
+       "version": "1.0.0",
+       "commands": { "search": { "description": "Search tweets" } }
+     },
+     "files": { "search.js": "module.exports = async function (args) { return {}; };" }
+   }
+   ```
+
+2. **Exec** a command against a real target. Args are ONE argument — a JSON
+   string (or plain text for a single-value command), not per-param flags:
+
+   ```sh
+   parall clip exec <clip> <command> '{"query":"AI","count":10}' --connection <ccn_id|alias>
+   # or route to a desktop (BYOC) device you own: --edge <edge-id>
+   # --connection and --edge are mutually exclusive; --timeout <ms> defaults to 30000
+   ```
+
+   A **cloud (hosted) profile is reachable ONLY via `--connection`** — the
+   binding its maintainer created IS the authorization. With neither flag the
+   server resolves only your own online desktop device, never a cloud profile.
+   Discover the bindings with `parall clip connections <clip>`.
+
+3. **Iterate**: edit locally → `parall clip publish` again → re-exec. Exec
+   resolves the file set from the REGISTRY, server-side — your own org always
+   runs the live working copy, i.e. the latest publish. It NEVER reads your
+   local directory: an edit you did not re-publish silently runs the previous
+   version.
+
+## Install model & self-development (v3)
+
+- Installing a clip is a **reference**, not a copy — the JS lives once in the Market DB.
+- **Your own org** always executes its **live working copy** (latest published files),
+  so re-publishing is your edit loop.
+- **Other orgs** installing your `public` clip execute only the **approved snapshot**
+  (`approved_version_id`); unreviewed public edits are invisible/unexecutable cross-org.
+- To customize someone else's public clip: install → **fetch its effective
+  file set** → modify → **publish into your OWN org** (a derived private
+  entry). You cannot edit a published clip in place. The CLI has no files
+  subcommand (`clip info` returns only the manifest) — read the source via
+  the API:
+
+  ```
+  GET /api/v1/orgs/{orgId}/clip-registry/{clipId}/files
+  ```
+
+  It returns exactly what you may read and execute: your own clip → the live
+  working copy; an installed public clip → the approved snapshot.
+
+## MCP clips (manifest-only)
+
+An MCP clip declares a remote MCP tool server. There is nothing to code: no
+`.js` files (the no-scripts refusal at publish applies to browser clips only),
+and the folder is just a manifest:
+
+```json
+{
+  "name": "linear",
+  "description": "Linear (MCP)",
+  "version": "1.0.0",
+  "type": "mcp",
+  "mcp": { "server_url": "https://mcp.linear.app/mcp", "auth": "oauth" }
+}
+```
+
+- The `mcp` block takes ONLY `server_url` and `auth` (`"none" | "bearer" |
+  "api_key" | "oauth"`). Any other key is refused at publish — a credential
+  belongs to the installing org's own configuration, NEVER to the clip
+  definition.
+- `server_url` must be an absolute **https** URL with no embedded credentials,
+  query, or fragment. It is review material, frozen with the approved version.
+- Do NOT put the server in the top-level `server` / `auth` manifest keys —
+  those are legacy Edge-manifest fields nothing reads. Only the `mcp` block
+  declares the server.
+- Both fields are optional, but what you declare is LOCKED: the installing
+  org's config must match it, and changing the URL or auth mode means
+  republishing.
+- Entering the credential / completing OAuth is a HUMAN step in the Clip
+  Console (the config-write endpoints are session-only — an API key cannot
+  call them). Once configured, discover the live tool schemas with
+  `parall clip tools <clip>` and exec like any other clip.
+- Publish is the same command: `parall clip publish ./my-clip/`.
+
+## Cloud (hosted) vs desktop (BYOC) Edge
+
+The same command JS runs on either. Hosted profiles are org-shared cloud browsers
+reachable ONLY via an explicit `--connection`; cloud state lives in S3 and is
+hydrated per pod. Your code never touches this — it just gets a `browser`/`tab`
+bound to whatever profile the connection selected.
+
+## Constraints
+
+- Browser clips: one command = one file; keep a command's work self-contained
+  (open what you need, close it, return). The Edge is stateless about your code
+  between calls.
+- Never embed credentials in the clip source — rely on the profile's logged-in
+  session (`tab.cookie` / `tab.fetch`). Published source is visible to installers.
+- Exec has a timeout (default 30s, caller-set up to 120s). Long scrapes should page,
+  not block.

package/skills/parall-clips/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: parall-clips
-description: "Parall clip operations: list installed clips and their connections, inspect clip commands/tools, execute clip commands on an explicit connection. Use when: the task requires external capabilities (GitHub, web search, etc.), user asks about available tools/clips, or you need to call a clip command."
+description: "Parall clip operations: list installed clips and their connections, inspect clip commands/tools, execute clip commands on an explicit connection. Use when: the task requires external capabilities (GitHub, web search, etc.), user asks about available tools/clips, or you need to call a clip command. For WRITING a new clip, use parall-clip-authoring instead."
 ---
 
 # Parall Clips