@parall/agent-core 1.52.1 → 1.53.0

package/src/skills/parall-clip-authoring.ts

@@ -0,0 +1,260 @@
+export const PARALL_CLIP_AUTHORING_SKILL = `# 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/src/skills/parall-clips.ts

@@ -1,41 +1,55 @@
 export const PARALL_CLIPS_SKILL = `# Parall Clips
 
 Clips are packaged capabilities that let agents operate external systems —
-APIs and websites — through named commands installed in the org.
+APIs, websites, remote tools — through named commands installed in the org.
 
 ## Discover
 
 \`\`\`bash
-parall clip list            # clips installed in this org
-parall clip info <alias>    # commands, params, version
+parall clip list               # installed clips + each clip's connections
+parall clip info <clip>        # commands + per-command params (manifest)
+parall clip connections <clip> # one clip's connections, full rows
+parall clip tools <clip>       # MCP clips only: live tool schemas
 \`\`\`
 
-## Invoke
+\`clip list\` answers both discovery questions at once: WHICH clip (name,
+description, version) and WHERE it can run — every connection with its
+\`ccn_…\` id, alias, and target kind:
 
-\`\`\`bash
-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"}'
-\`\`\`
-
-Results are JSON on stdout; failures print an error.
+- \`cloud\` — an org-shared cloud profile (a maintainer's signed-in browser)
+- \`desktop\` — a member's own device (only its owner can exec through it)
+- \`mcp\` — a remote MCP tool server
+- \`device\` — a device whose placement could not be resolved just now (the
+  device list was unavailable); don't guess which kind it is — re-run
+  discovery, and treat a persistent \`device\` like an unverified target
+- \`orphaned\` — the target device is gone; the connection is unusable
 
-## Execute on an Edge device (registry clips)
+Pick the connection whose alias names the account/device the task needs
+(e.g. \`ins-nyc\` vs \`ins-boston\`). A row without an alias can only be
+referenced by \`ccn_\` id — when aliases are missing and several connections
+could match, ask a human to name them in the Clip Console rather than
+guessing which signed-in account you are about to act through.
 
-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.
+## Execute
 
 \`\`\`bash
-parall clip exec <clip> <command> [args] --connection <id|alias>  # the normal form
+parall clip exec <clip> <command> [args] --connection <ccn_|alias>  # the normal form
 parall clip exec browser-tools screenshot '{"url":"…"}' --connection cloud-main
 \`\`\`
 
+Build \`args\` as JSON per the command's params from \`clip info\` (or the
+tool's \`inputSchema\` from \`clip tools\` for MCP clips — tool names are NOT
+frozen in the manifest, so never guess a tool name or its argument shape).
+Results are JSON on stdout; failures print a typed error.
+
+**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.
+
 - 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.
+  connection its maintainer bound. 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.
 - Waiting on a cloud profile is handled by the CLI: \`EDGE_ACTIVATING\` (cold
   start), \`EDGE_BUSY\` (another exec is running) and
@@ -47,19 +61,10 @@ parall clip exec browser-tools screenshot '{"url":"…"}' --connection cloud-mai
 
 ## MCP clips (remote tool servers)
 
-Some registry clips are backed by a remote MCP server instead of an Edge
-device. The command is an MCP tool name and the args are that tool's JSON
-arguments — but **MCP tool names are NOT frozen in \`clip info\`, so discover
-them first; never guess a tool name or its argument shape**. Before invoking,
-find the connection AND the tool schemas:
-
-\`\`\`bash
-parall clip connections <alias>   # the ccn_ id / alias to pass to --connection
-parall clip tools <alias>         # tool names + descriptions + inputSchema (JSON)
-\`\`\`
-
-Read each tool's \`inputSchema\` from \`clip tools\` to build valid args, then
-exec against that explicit target — same form as an Edge clip:
+A connection with target \`mcp\` routes to a remote MCP server; the command
+is an MCP tool name and the args are that tool's JSON arguments. Read each
+tool's \`inputSchema\` from \`clip tools\` first, then exec against the
+explicit target — the same form as any other clip:
 
 \`\`\`bash
 parall clip exec <clip> <tool> [json-args] --connection <ccn_|alias>
@@ -77,13 +82,11 @@ parall clip exec <clip> <tool> [json-args] --connection <ccn_|alias>
 
 ## Behavior rules
 
-- 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
+- An authorization error (\`HOSTED_CONNECTION_REQUIRED\`, \`FORBIDDEN\`) is a
+  fail-fast: ask the clip's maintainer or an org admin to bind the clip or
+  grant the connection — do not retry or work around it.
+- If the target device is offline or the call times out, report that
   plainly; do not queue, and never fabricate a result for a run that errored.
-- 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
@@ -99,6 +102,8 @@ parall clip exec <clip> <tool> [json-args] --connection <ccn_|alias>
 - 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.
+  The connection's alias/target tells you WHICH account you are acting as —
+  if that is ambiguous, resolve it with a human before acting, not after.
 - Reach for \`parall clip list\` whenever a task needs capabilities beyond
   built-in tools.
 `;