@parall/cli 1.52.0 → 1.52.2

package/dist/commands/clip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clip.d.ts","sourceRoot":"","sources":["../../src/commands/clip.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgCpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QAiSpD"}
+{"version":3,"file":"clip.d.ts","sourceRoot":"","sources":["../../src/commands/clip.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiFpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QA2XpD"}

package/dist/commands/clip.js

@@ -1,53 +1,97 @@
 import { resolveCredentials } from '../lib/client.js';
-import { invokeClipAwaitingActivation } from '../lib/clip-invoke.js';
 import { execEdgeClipWithBoundedWait } from '../lib/edge-exec.js';
 import { printJson, printError, parsePositiveInt } from '../lib/output.js';
-/**
- * Derive a CLI-friendly alias from a registry source string.
- * Handles scoped packages ("@scope/name@1.0.0" → "name") and
- * plain packages ("name@1.0.0" → "name").
- */
-function deriveAlias(source) {
-    let s = source.trim();
-    if (s.startsWith('@')) {
-        const slashIdx = s.indexOf('/');
-        if (slashIdx > 0) {
-            const rest = s.slice(slashIdx + 1);
-            const atIdx = rest.indexOf('@');
-            s = atIdx > 0 ? rest.slice(0, atIdx) : rest;
+import { buildPublishedManifest, collectPublishSource } from '../lib/publish-source.js';
+const NO_ALIAS_HINT = 'no alias — reference this connection by its ccn_ id, or ask a human to name it in the Clip Console so callers can tell the accounts apart';
+function connectionAnnotations(conn, deviceById) {
+    const out = { target: 'orphaned' };
+    if (conn.mcp_config_id) {
+        out.target = 'mcp';
+    }
+    else if (conn.device_id) {
+        const device = deviceById?.get(conn.device_id);
+        if (!device) {
+            // Absent row ≠ deleted device: the device list may have failed to load
+            // (deviceById null) or lag a concurrent delete. 'orphaned' is reserved
+            // for the provable case (device_id itself nulled by the server).
+            out.target = 'device';
+        }
+        else if (device.placement === 'hosted') {
+            out.target = 'cloud';
+            out.device = device.name;
         }
+        else {
+            out.target = 'desktop';
+            out.device = device.name;
+            out.device_status = device.status;
+        }
+    }
+    if (!conn.alias)
+        out.hint = NO_ALIAS_HINT;
+    return out;
+}
+/** Compact connection form for discovery output (`clip list`). */
+function summarizeConnection(conn, deviceById) {
+    return {
+        id: conn.id,
+        alias: conn.alias ?? null,
+        ...(conn.profile ? { profile: conn.profile } : {}),
+        ...connectionAnnotations(conn, deviceById),
+    };
+}
+/** Device index for annotating connections; null = list unavailable (degrade
+ *  to target 'device' rather than failing discovery or guessing placement). */
+async function loadDeviceIndex(client, orgId) {
+    try {
+        const resp = await client.listEdgeDevices(orgId);
+        return new Map((resp.data ?? []).map((d) => [d.id, d]));
     }
-    else {
-        const atIdx = s.indexOf('@');
-        if (atIdx > 0)
-            s = s.slice(0, atIdx);
+    catch {
+        return null;
     }
-    // Normalize to server's allowed alias charset: ^[a-z0-9][a-z0-9-_]*$
-    return s
-        .toLowerCase()
-        .replace(/[^a-z0-9-_]/g, '-')
-        .replace(/^[^a-z0-9]+/, '');
 }
 export function registerClipCommands(program) {
-    const clip = program.command('clip').description('Manage clips');
+    const clip = program
+        .command('clip')
+        .description('Discover, install and execute clips installed in the organization');
     clip
         .command('list')
-        .description('List clips in the organization')
+        .description('List clips installed in the organization, each with its connections — the --connection refs `clip exec` takes')
         .action(async () => {
         try {
             const { client, orgId } = resolveCredentials();
-            const clips = await client.listClips(orgId);
-            // Table display: alias, name, version, status, source_type
+            // Reads the v3 registry installs. The legacy listClips() reads the v2
+            // `clips` table, whose machine-bound registry installs are retired — a
+            // clip installed through the Console never appeared there, which is why
+            // this command used to under-report.
+            const clips = await client.listInstalledRegistryClips(orgId);
             if (clips.length === 0) {
-                printJson({ data: [], message: 'No clips found' });
+                printJson({ data: [], message: 'No clips installed' });
                 return;
             }
-            const rows = clips.map((c) => ({
-                alias: c.alias,
-                name: c.name,
-                version: c.version ?? '-',
-                status: c.status,
-                source_type: c.source_type,
+            const deviceById = await loadDeviceIndex(client, orgId);
+            // One list answers both discovery questions — WHICH clip and WHERE it
+            // can run — so an agent resolves "call <clip> for me" in a single
+            // command instead of a per-clip connections crawl.
+            const rows = await Promise.all(clips.map(async (c) => {
+                const row = {
+                    id: c.id,
+                    name: c.name,
+                    ...(c.description ? { description: c.description } : {}),
+                    version: c.version ?? '-',
+                    visibility: c.visibility,
+                };
+                try {
+                    const resp = await client.listClipConnections(orgId, c.id);
+                    row.connections = (resp.data ?? []).map((conn) => summarizeConnection(conn, deviceById));
+                }
+                catch (err) {
+                    // One clip's broken connections read must not take down
+                    // discovery of every other clip — degrade that row, honestly.
+                    row.connections = null;
+                    row.connections_error = err instanceof Error ? err.message : String(err);
+                }
+                return row;
             }));
             printJson(rows);
         }
@@ -57,23 +101,25 @@ export function registerClipCommands(program) {
     });
     clip
         .command('install')
-        .description('Install a clip from a registry source')
-        .argument('<source>', 'Registry source identifier (used as name and alias)')
-        .option('--alias <alias>', 'Override the alias (default: derived from source)')
-        .requiredOption('-m, --machine-id <machineId>', 'Machine ID that runs this clip')
-        .action(async (source, opts) => {
+        .description('Install a registry clip into the organization')
+        .argument('<clip>', 'Registry clip id (crg_...) or name')
+        .action(async (clip) => {
         try {
             const { client, orgId } = resolveCredentials();
-            // Derive alias: take the last segment, replace non-alphanumeric with dash, lowercase.
-            const alias = opts.alias ?? deriveAlias(source);
-            const req = {
-                alias,
-                source_type: 'registry',
-                source_ref: source,
-                machine_id: opts.machineId,
-            };
-            const clip = await client.createClip(orgId, req);
-            printJson(clip);
+            // v3 installs a REFERENCE into clip_installs, keyed by the registry id.
+            // There is no machine to pick: a v3 clip runs wherever the connection
+            // it is bound to points, which is why the old --machine-id is gone.
+            // listOrgRegistryClips is the surface carrying `crg_` ids — the Pinix
+            // catalog proxy does not.
+            const registry = await client.listOrgRegistryClips(orgId);
+            const found = registry.find((c) => c.id === clip || c.name === clip);
+            if (!found) {
+                printError(new Error(`No registry clip matching "${clip}". Pass a crg_ id or the exact registry name; a private clip from another org is not installable.`));
+                return;
+            }
+            // Idempotent server-side: installing an already-installed clip is a no-op.
+            const resp = await client.installRegistryClip(orgId, found.id);
+            printJson({ ...resp, id: found.id, name: found.name });
         }
         catch (err) {
             printError(err);
@@ -81,29 +127,65 @@ export function registerClipCommands(program) {
     });
     clip
         .command('info')
-        .description('Show detailed information about a clip by alias')
-        .argument('<alias>', 'Clip alias')
-        .action(async (alias) => {
+        .description("Show detailed clip information, including its manifest commands and params. For your org's OWN clips this includes review_status/review_note (the platform-review state of a public publish)")
+        .argument('<clip>', 'Registry clip id (crg_...) or name')
+        .action(async (clip) => {
         try {
             const { client, orgId } = resolveCredentials();
-            const clips = await client.listClips(orgId);
-            const found = clips.find((c) => c.alias === alias);
+            // Resolve installed-first (the historical semantic), then fall back to
+            // the org registry: an author checking a clip they published but never
+            // installed — the publish→review→revise loop — must not dead-end here.
+            const installed = await client.listInstalledRegistryClips(orgId);
+            let found = installed.find((c) => c.id === clip || c.name === clip);
             if (!found) {
-                printError(new Error(`Clip with alias "${alias}" not found`));
+                const registry = await client.listOrgRegistryClips(orgId);
+                found = registry.find((c) => c.id === clip || c.name === clip);
+            }
+            let entry = found;
+            if (found) {
+                // The detail read is what carries review_status/review_note (server
+                // attaches them only for the owning org). A cross-org entry can lose
+                // detail visibility between the list and this read — the list entry
+                // is still correct data, so fall back to it rather than failing info.
+                try {
+                    entry = await client.getRegistryClip(orgId, found.id);
+                }
+                catch {
+                    entry = found;
+                }
+            }
+            else if (clip.startsWith('crg_')) {
+                // Both lists are single pages (registry capped at 100 entries), so a
+                // valid id can sit beyond them — an exact crg_ id needs no list
+                // resolution at all; go straight to the detail endpoint before
+                // concluding not-found.
+                try {
+                    entry = await client.getRegistryClip(orgId, clip);
+                }
+                catch {
+                    // fall through to the not-found error below
+                }
+            }
+            if (!entry) {
+                // `return` matters: without it the lookup falls through and dies
+                // with a TypeError instead of the message just printed.
+                printError(new Error(`No clip matching "${clip}" (see \`parall clip list\`)`));
+                return;
             }
-            // Display full details including manifest commands
             const info = {
-                id: found.id,
-                alias: found.alias,
-                name: found.name,
-                version: found.version,
-                description: found.description,
-                status: found.status,
-                source_type: found.source_type,
-                source_ref: found.source_ref,
-                manifest: found.manifest,
-                created_at: found.created_at,
-                updated_at: found.updated_at,
+                id: entry.id,
+                name: entry.name,
+                version: entry.version,
+                description: entry.description,
+                visibility: entry.visibility,
+                manifest: entry.manifest,
+                created_at: entry.created_at,
+                updated_at: entry.updated_at,
+                // Approved pointer = the snapshot cross-org installs serve; absent =
+                // never approved. review_* appear only for this org's own clips.
+                ...(entry.approved_version_id ? { approved_version_id: entry.approved_version_id } : {}),
+                ...(entry.review_status ? { review_status: entry.review_status } : {}),
+                ...(entry.review_note ? { review_note: entry.review_note } : {}),
             };
             printJson(info);
         }
@@ -113,22 +195,30 @@ export function registerClipCommands(program) {
     });
     clip
         .command('connections')
-        .description('List clip connections (Edge device/profile or MCP bindings) for a clip by alias')
-        .argument('<alias>', 'Clip alias')
-        .action(async (alias) => {
+        .description("List a clip's connections in full — each row's ccn_ id or alias is what `clip exec --connection` takes")
+        .argument('<clip>', 'Registry clip id (crg_...) or name')
+        .action(async (clip) => {
         try {
             const { client, orgId } = resolveCredentials();
-            // Resolve alias to clip ID — same lookup `clip info` uses
-            const clips = await client.listClips(orgId);
-            const found = clips.find((c) => c.alias === alias);
+            // clip_connections.clip_id is a foreign key onto clip_registry, so this
+            // endpoint is keyed by the REGISTRY id. Resolving through the legacy
+            // listClips() handed it a `clp_` id from the v2 table, which matches
+            // nothing — the command returned an empty list for every clip.
+            const installed = await client.listInstalledRegistryClips(orgId);
+            const found = installed.find((c) => c.id === clip || c.name === clip);
             if (!found) {
-                printError(new Error(`Clip with alias "${alias}" not found`));
+                printError(new Error(`No installed clip matching "${clip}" (pass a crg_ id or the registry name; see \`parall clip list\`)`));
+                return;
             }
             const resp = await client.listClipConnections(orgId, found.id);
             // A Go nil slice serializes as `null`, not `[]` — normalize so an
             // empty result always prints `[]` (ts/AGENTS.md § Cross-Language
             // Contract Edge Cases).
-            printJson(resp.data ?? []);
+            const conns = resp.data ?? [];
+            const deviceById = conns.some((c) => c.device_id)
+                ? await loadDeviceIndex(client, orgId)
+                : new Map();
+            printJson(conns.map((c) => ({ ...c, ...connectionAnnotations(c, deviceById) })));
         }
         catch (err) {
             printError(err);
@@ -136,16 +226,17 @@ export function registerClipCommands(program) {
     });
     clip
         .command('tools')
-        .description('List the MCP tool schemas (name, description, inputSchema) of an MCP clip by alias — the discovery step before `clip exec <clip> <tool>`')
-        .argument('<alias>', 'Clip alias')
-        .action(async (alias) => {
+        .description('List the MCP tool schemas (name, description, inputSchema) of an MCP clip — the discovery step before `clip exec <clip> <tool>`')
+        .argument('<clip>', 'Registry clip id (crg_...) or name')
+        .action(async (clip) => {
         try {
             const { client, orgId } = resolveCredentials();
-            // Resolve alias to clip ID — same lookup `clip connections`/`info` use.
-            const clips = await client.listClips(orgId);
-            const found = clips.find((c) => c.alias === alias);
+            // Same lookup `clip connections`/`info` use.
+            const installed = await client.listInstalledRegistryClips(orgId);
+            const found = installed.find((c) => c.id === clip || c.name === clip);
             if (!found) {
-                printError(new Error(`Clip with alias "${alias}" not found`));
+                printError(new Error(`No installed clip matching "${clip}" (see \`parall clip list\`)`));
+                return;
             }
             // MCP tools are NOT frozen in the clip manifest, so `clip info` cannot
             // show them; the live server snapshot behind getClipMCPConfig is the
@@ -160,62 +251,18 @@ export function registerClipCommands(program) {
             printError(err);
         }
     });
-    clip
-        .command('invoke')
-        .description('Invoke a clip command')
-        .argument('<alias>', 'Clip alias')
-        .argument('<command>', 'Command name to invoke')
-        .argument('[input]', 'Input data (JSON string or plain text)')
-        .option('--timeout <ms>', 'Timeout in milliseconds', '30000')
-        .action(async (alias, command, input, opts) => {
-        try {
-            const { client, orgId } = resolveCredentials();
-            // Parse input: try JSON first, fall back to plain text wrapping.
-            let parsedInput = undefined;
-            if (input !== undefined) {
-                try {
-                    parsedInput = JSON.parse(input);
-                }
-                catch {
-                    // Not valid JSON — send as a plain string.
-                    parsedInput = input;
-                }
-            }
-            let timeoutMs;
-            if (opts?.timeout) {
-                timeoutMs = parseInt(opts.timeout, 10);
-                if (isNaN(timeoutMs) || timeoutMs <= 0) {
-                    printError(new Error('--timeout must be a positive integer (milliseconds)'));
-                }
-            }
-            const req = {
-                alias,
-                command,
-                input: parsedInput,
-                timeout_ms: timeoutMs,
-            };
-            // Hosted-browser clips may hit a cold profile: absorb the (pre-dispatch,
-            // side-effect-free) BROWSER_PROFILE_ACTIVATING window here instead of
-            // making every agent hand-roll a retry loop. See lib/clip-invoke.ts.
-            const result = await invokeClipAwaitingActivation(client, orgId, req);
-            if (result.error) {
-                printError(new Error(result.error));
-            }
-            else {
-                printJson(result.output);
-            }
-        }
-        catch (err) {
-            printError(err);
-        }
-    });
+    // `clip invoke` (the v2 clip-service path) is deliberately GONE, not hidden:
+    // discovery above lists v3 registry installs only, and a v3 name fed to the
+    // v2 invoke endpoint answered CLIP_NOT_FOUND — a dead verb that only misled
+    // callers into the wrong invocation path. `clip exec` is the one execution
+    // verb; the server endpoint retires separately with the rest of v2.
     clip
         .command('exec')
         .description('Execute a registry (Edge) clip command on an Edge device. A cloud (hosted) profile is reachable ONLY via --connection; with neither --connection nor --edge, the server resolves just your OWN online desktop device (legacy BYOC fallback — never a cloud profile)')
         .argument('<clip>', 'Clip name in the org clip registry')
         .argument('<command>', 'Command name to execute')
         .argument('[args]', 'Command arguments (JSON string or plain text)')
-        .option('--connection <ref>', 'Clip connection id (ccn_…) or alias. REQUIRED to reach a cloud (hosted) profile — the binding its maintainer created is the authorization')
+        .option('--connection <ref>', 'Clip connection id (ccn_…) or alias — discover them with `parall clip connections <clip>`. REQUIRED to reach a cloud (hosted) profile: the binding its maintainer created is the authorization')
         .option('--edge <edgeId>', 'A desktop (BYOC) device you own. Mutually exclusive with --connection')
         .option('--profile <name>', 'Browser profile (with --connection it may only restate the granted one)')
         .option('--timeout <ms>', 'Execution timeout in milliseconds', '30000')
@@ -271,21 +318,69 @@ export function registerClipCommands(program) {
             printError(err);
         }
     });
+    clip
+        .command('publish')
+        .description('Publish a clip directory (manifest.json or site.json + its top-level .js files) into the org registry. Re-publishing an existing name is author-only and replaces the file set; "visibility": "public" additionally submits the version for platform review before it can spread cross-org')
+        .argument('<directory>', 'Clip source directory')
+        .action(async (directory) => {
+        try {
+            const { client, orgId } = resolveCredentials();
+            const { manifest, files, directoryName } = collectPublishSource(directory);
+            // Same request derivation as the Edge CLI (`parall-clip publish`):
+            // manifest fields win, directory name / 0.0.1 / private fill the gaps.
+            // Send the TRIMMED values — name is the org-wide upsert key, so
+            // `" google "` must not mint an entry distinct from `google`.
+            const manifestName = typeof manifest.name === 'string' ? manifest.name.trim() : '';
+            const manifestVersion = typeof manifest.version === 'string' ? manifest.version.trim() : '';
+            const entry = await client.publishRegistryClip(orgId, {
+                name: manifestName !== '' ? manifestName : directoryName,
+                description: typeof manifest.description === 'string' ? manifest.description : undefined,
+                version: manifestVersion !== '' ? manifestVersion : '0.0.1',
+                visibility: manifest.visibility === 'public' ? 'public' : 'private',
+                manifest: buildPublishedManifest(manifest),
+                files,
+            });
+            printJson({
+                id: entry.id,
+                name: entry.name,
+                version: entry.version ?? null,
+                visibility: entry.visibility,
+                files: Object.keys(files).sort(),
+                // Present only when a public publish queued a review submission.
+                ...(entry.review_status ? { review_status: entry.review_status } : {}),
+            });
+            if (entry.review_status === 'pending') {
+                // stderr, keeping stdout parseable — same convention as printRefHint.
+                // A public publish is NOT cross-org visible until platform review
+                // approves; tell the publisher where to watch that state.
+                console.error(`Review pending: this clip stays invisible to other orgs until platform review approves it (your own org can use it immediately). ` +
+                    `Check status with \`parall clip info ${entry.name}\` (review_status / review_note) ` +
+                    `or GET /api/v1/orgs/${orgId}/clip-registry/${entry.id}.`);
+            }
+        }
+        catch (err) {
+            printError(err);
+        }
+    });
     clip
         .command('remove')
-        .description('Remove a clip by alias')
-        .argument('<alias>', 'Clip alias')
-        .action(async (alias) => {
+        .description("Remove the organization's install of a clip")
+        .argument('<clip>', 'Registry clip id (crg_...) or name')
+        .action(async (clip) => {
         try {
             const { client, orgId } = resolveCredentials();
-            // Resolve alias to clip ID
-            const clips = await client.listClips(orgId);
-            const found = clips.find((c) => c.alias === alias);
+            // Uninstall drops the org's reference in clip_installs. The v2
+            // deleteClip() operates on a different table and cannot reach a clip
+            // installed through the registry — it would report "not found" for one
+            // that plainly shows up in `clip list`.
+            const installed = await client.listInstalledRegistryClips(orgId);
+            const found = installed.find((c) => c.id === clip || c.name === clip);
             if (!found) {
-                printError(new Error(`Clip with alias "${alias}" not found`));
+                printError(new Error(`No installed clip matching "${clip}" (see \`parall clip list\`)`));
+                return;
             }
-            await client.deleteClip(orgId, found.id);
-            printJson({ ok: true, removed: alias });
+            await client.uninstallRegistryClip(orgId, found.id);
+            printJson({ ok: true, removed: found.name, id: found.id });
         }
         catch (err) {
             printError(err);

package/dist/commands/messages.d.ts

@@ -1,3 +1,33 @@
 import type { Command } from 'commander';
+/**
+ * Message ↔ session/step attribution for a send. Lane context WINS over the
+ * process-level runtime context: the lane file is written per dispatch (a
+ * fork turn carries its child ase_/step), while PRLL_CONTEXT_FILE on
+ * single-process runtimes (codex app-server) is pinned to the MAIN session
+ * for the process's whole life — letting it win stamps fork replies and
+ * their dispatch rows with main's session. Runtime context only fills what
+ * the lane context does not provide.
+ *
+ * session and step are resolved as a PAIR, never independently: the server
+ * validates agent_step_id first and derives agent_session_id FROM that step,
+ * ignoring the supplied session whenever the step is valid (its check is
+ * chat-level, so a main-session step passes for a same-chat fork); when the
+ * step is stale it falls back to the supplied session instead. Either half
+ * can therefore decide the attribution, so a pair mixed from two sources has
+ * no single correct reading. The lane file writes session_id and step_id
+ * independently and may carry either alone — so once the lane supplies ANY
+ * attribution it owns both fields, and the runtime fills a gap only when it
+ * demonstrably describes the same session the lane names.
+ */
+export declare function resolveSendAttribution(ctx: {
+    sessionId?: string;
+    stepId?: string;
+}, laneCtx: {
+    sessionId?: string;
+    stepId?: string;
+} | null): {
+    sessionId?: string;
+    stepId?: string;
+};
 export declare function registerMessageCommands(program: Command): void;
 //# sourceMappingURL=messages.d.ts.map

package/dist/commands/messages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/commands/messages.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmBzC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,QAsPvD"}
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/commands/messages.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmBzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,EAC5C,OAAO,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GACtD;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CASzC;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,QAoPvD"}

package/dist/commands/messages.js

@@ -4,6 +4,36 @@ import { LaneContextError, markLaneReplyCommitted, resolveCredentials, resolveLa
 import { printError, printJson, printRefHint, stripPrllScheme } from '../lib/output.js';
 import { NO_BODY_ERROR, resolveMessageText, TEXT_FILE_OPTION_DESC, TEXT_OPTION_DESC, } from '../lib/text-input.js';
 import { uploadFile } from '../lib/upload.js';
+/**
+ * Message ↔ session/step attribution for a send. Lane context WINS over the
+ * process-level runtime context: the lane file is written per dispatch (a
+ * fork turn carries its child ase_/step), while PRLL_CONTEXT_FILE on
+ * single-process runtimes (codex app-server) is pinned to the MAIN session
+ * for the process's whole life — letting it win stamps fork replies and
+ * their dispatch rows with main's session. Runtime context only fills what
+ * the lane context does not provide.
+ *
+ * session and step are resolved as a PAIR, never independently: the server
+ * validates agent_step_id first and derives agent_session_id FROM that step,
+ * ignoring the supplied session whenever the step is valid (its check is
+ * chat-level, so a main-session step passes for a same-chat fork); when the
+ * step is stale it falls back to the supplied session instead. Either half
+ * can therefore decide the attribution, so a pair mixed from two sources has
+ * no single correct reading. The lane file writes session_id and step_id
+ * independently and may carry either alone — so once the lane supplies ANY
+ * attribution it owns both fields, and the runtime fills a gap only when it
+ * demonstrably describes the same session the lane names.
+ */
+export function resolveSendAttribution(ctx, laneCtx) {
+    if (!laneCtx?.sessionId && !laneCtx?.stepId) {
+        return { sessionId: ctx.sessionId, stepId: ctx.stepId };
+    }
+    const sameSession = laneCtx.sessionId !== undefined && laneCtx.sessionId === ctx.sessionId;
+    return {
+        sessionId: laneCtx.sessionId,
+        stepId: laneCtx.stepId ?? (sameSession ? ctx.stepId : undefined),
+    };
+}
 export function registerMessageCommands(program) {
     const messages = program.command('messages').description('Manage messages');
     messages
@@ -129,10 +159,6 @@ export function registerMessageCommands(program) {
                 req.thread_root_id = threadRootId;
             if (opts.reply === false)
                 req.hints = { no_reply: true };
-            if (ctx.stepId)
-                req.agent_step_id = ctx.stepId;
-            if (ctx.sessionId)
-                req.agent_session_id = ctx.sessionId;
             // Dispatch lane binding (PRLL_CONTEXT_DIR contract): a send whose
             // exact (chat, thread) target has an active lane context rides the
             // server's dispatch ledger — the lane token authorizes the write,
@@ -143,6 +169,11 @@ export function registerMessageCommands(program) {
             // per-invocation idempotency key. All of this stays out of the
             // model's view.
             const laneCtx = resolveLaneDispatchContext(chatId, threadRootId);
+            const attribution = resolveSendAttribution(ctx, laneCtx);
+            if (attribution.stepId)
+                req.agent_step_id = attribution.stepId;
+            if (attribution.sessionId)
+                req.agent_session_id = attribution.sessionId;
             let usedReplyKey = false;
             if (laneCtx) {
                 req.dispatch_lane = laneCtx.lane;
@@ -153,10 +184,6 @@ export function registerMessageCommands(program) {
                 else {
                     req.idempotency_key = `cli:${randomUUID()}`;
                 }
-                if (!req.agent_step_id && laneCtx.stepId)
-                    req.agent_step_id = laneCtx.stepId;
-                if (!req.agent_session_id && laneCtx.sessionId)
-                    req.agent_session_id = laneCtx.sessionId;
             }
             else {
                 // By-source dispatch binding (parel — PRLL_DISPATCH_SOURCE_* env,

package/dist/commands/wechat.d.ts

@@ -0,0 +1,12 @@
+import { Command } from 'commander';
+/**
+ * `parall wechat …` — the per-vendor platform verb for the personal-WeChat
+ * protocol channel (wechatapi.net, tier B in the multi-channel
+ * architecture). The agent sends as the connected WeChat account itself;
+ * the vendor token + device id never reach the runtime — api-server
+ * performs the vendor call in-process.
+ * INTERNAL research preview: the capability is flag-gated to the internal
+ * org. Design: docs/engineering-design/wechat-channel-design.md §3.
+ */
+export declare function registerWechatCommands(program: Command): void;
+//# sourceMappingURL=wechat.d.ts.map

package/dist/commands/wechat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wechat.d.ts","sourceRoot":"","sources":["../../src/commands/wechat.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,QA6CtD"}

package/dist/commands/wechat.js

@@ -0,0 +1,49 @@
+import { resolveCredentials } from '../lib/client.js';
+import { printError, printJson } from '../lib/output.js';
+/**
+ * `parall wechat …` — the per-vendor platform verb for the personal-WeChat
+ * protocol channel (wechatapi.net, tier B in the multi-channel
+ * architecture). The agent sends as the connected WeChat account itself;
+ * the vendor token + device id never reach the runtime — api-server
+ * performs the vendor call in-process.
+ * INTERNAL research preview: the capability is flag-gated to the internal
+ * org. Design: docs/engineering-design/wechat-channel-design.md §3.
+ */
+export function registerWechatCommands(program) {
+    const wechat = program
+        .command('wechat')
+        .description('WeChat channel platform verbs (agent-only; sends as the connected account)');
+    wechat
+        .command('send')
+        .description('Send a message to a WeChat conversation this connection has seen inbound')
+        .requiredOption('--to <wxid>', 'Vendor-native conversation id from the inbound event (a friend wxid, or a room id ending in @chatroom)')
+        .requiredOption('--text <text>', 'Message text (plain text)')
+        .option('--at <wxid>', 'In group replies: @-mention one member (wxid of the person you are answering)')
+        .action(async (opts) => {
+        try {
+            const { client, orgId } = resolveCredentials();
+            const sent = await client.sendChannelMessage(orgId, {
+                channel_type: 'wechat',
+                conversation_id: opts.to,
+                text: opts.text,
+                ...(opts.at ? { at: opts.at } : {}),
+            });
+            printJson(sent);
+        }
+        catch (err) {
+            printError(err);
+        }
+    });
+    wechat
+        .command('contacts')
+        .description('List the account address book: friend wxids, saved group room ids, followed official accounts (ids only — the vendor returns no names)')
+        .action(async () => {
+        try {
+            const { client, orgId } = resolveCredentials();
+            printJson(await client.listWechatContacts(orgId));
+        }
+        catch (err) {
+            printError(err);
+        }
+    });
+}

package/dist/index.js

@@ -21,6 +21,7 @@ import { registerFileCommands } from './commands/files.js';
 import { registerMachineCommands } from './commands/machines.js';
 import { registerClipCommands } from './commands/clip.js';
 import { registerSlackCommands } from './commands/slack.js';
+import { registerWechatCommands } from './commands/wechat.js';
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
 const program = new Command();
@@ -48,4 +49,5 @@ registerFileCommands(program);
 registerMachineCommands(program);
 registerClipCommands(program);
 registerSlackCommands(program);
+registerWechatCommands(program);
 program.parse();

package/dist/lib/publish-source.d.ts

@@ -0,0 +1,14 @@
+export interface PublishSource {
+    manifest: Record<string, unknown>;
+    files: Record<string, string>;
+    directoryName: string;
+}
+export declare function collectPublishSource(directory: string): PublishSource;
+/**
+ * The manifest subset that gets stored in the registry: the commands map plus
+ * the metadata keys the exec/display sides read. Mirrors the Edge CLI's
+ * buildPublishedManifest — local-only fields (name/version/visibility ride as
+ * top-level request fields) stay out of the stored manifest.
+ */
+export declare function buildPublishedManifest(manifest: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=publish-source.d.ts.map

package/dist/lib/publish-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-source.d.ts","sourceRoot":"","sources":["../../src/lib/publish-source.ts"],"names":[],"mappings":"AA8BA,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;CACvB;AA4FD,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAmCrE;AAsBD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASjG"}

package/dist/lib/publish-source.js

@@ -0,0 +1,158 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, readdirSync, realpathSync, statSync, } from 'node:fs';
+import { basename, isAbsolute, join, relative, sep } from 'node:path';
+function fileIdentityMatches(a, b) {
+    return a.dev === b.dev && a.ino === b.ino;
+}
+function assertContained(root, candidate, name) {
+    const pathFromRoot = relative(root, candidate);
+    if (pathFromRoot === '..' || pathFromRoot.startsWith(`..${sep}`) || isAbsolute(pathFromRoot)) {
+        throw new Error(`Publish source escapes the clip directory: ${name}`);
+    }
+}
+function assertSourceRootIdentity(root, expected) {
+    let current;
+    try {
+        current = lstatSync(root);
+    }
+    catch {
+        throw new Error('Publish source directory changed while reading');
+    }
+    if (!current.isDirectory() || !fileIdentityMatches(expected, current)) {
+        throw new Error('Publish source directory changed while reading');
+    }
+}
+function readRegularFile(root, name) {
+    if (basename(name) !== name)
+        throw new Error(`Invalid publish source path: ${name}`);
+    const path = join(root, name);
+    const metadata = lstatSync(path);
+    if (metadata.isSymbolicLink())
+        throw new Error(`Publish source must not be a symlink: ${name}`);
+    if (!metadata.isFile())
+        throw new Error(`Publish source must be a regular file: ${name}`);
+    if (metadata.nlink !== 1)
+        throw new Error(`Publish source must not be a hard link: ${name}`);
+    const realPath = realpathSync(path);
+    assertContained(root, realPath, name);
+    const noFollow = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
+    let descriptor;
+    try {
+        descriptor = openSync(path, constants.O_RDONLY | noFollow);
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === 'ELOOP' || code === 'EMLINK') {
+            throw new Error(`Publish source must not be a symlink: ${name}`);
+        }
+        throw error;
+    }
+    try {
+        const openedMetadata = fstatSync(descriptor);
+        if (!fileIdentityMatches(metadata, openedMetadata)) {
+            throw new Error(`Publish source changed while opening: ${name}`);
+        }
+        if (!openedMetadata.isFile()) {
+            throw new Error(`Publish source must be a regular file: ${name}`);
+        }
+        if (openedMetadata.nlink !== 1) {
+            throw new Error(`Publish source must not be a hard link: ${name}`);
+        }
+        return readFileSync(descriptor, 'utf8');
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function readManifest(root, entries, displayDirectory) {
+    const manifestNames = ['manifest.json', 'site.json'].filter((name) => entries.has(name));
+    if (manifestNames.length === 0) {
+        throw new Error(`No manifest.json or site.json found in ${displayDirectory}`);
+    }
+    let lastError;
+    for (const manifestName of manifestNames) {
+        // A readRegularFile refusal (symlink, swap, escape) propagates — safety
+        // refusals are not "try the next manifest" territory; only parse failures
+        // fall through to site.json.
+        const raw = readRegularFile(root, manifestName);
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                throw new Error('manifest must be a JSON object');
+            }
+            return parsed;
+        }
+        catch (error) {
+            lastError = new Error(`Invalid ${manifestName}: ${error.message}`);
+        }
+    }
+    throw lastError;
+}
+export function collectPublishSource(directory) {
+    let root;
+    let rootMetadata;
+    try {
+        root = realpathSync(directory);
+        rootMetadata = statSync(root);
+        if (!rootMetadata.isDirectory())
+            throw new Error('not a directory');
+    }
+    catch {
+        throw new Error(`Clip directory is unavailable: ${directory}`);
+    }
+    const entries = new Map(readdirSync(root, { withFileTypes: true }).map((entry) => [entry.name, entry]));
+    assertSourceRootIdentity(root, rootMetadata);
+    const manifest = readManifest(root, entries, directory);
+    assertSourceRootIdentity(root, rootMetadata);
+    const scriptNames = [...entries.keys()].filter((name) => name.endsWith('.js')).sort();
+    if (scriptNames.length === 0) {
+        throw new Error(`No .js files found in ${directory}`);
+    }
+    const files = {};
+    for (const name of scriptNames) {
+        assertSourceRootIdentity(root, rootMetadata);
+        files[name] = readRegularFile(root, name);
+        assertSourceRootIdentity(root, rootMetadata);
+    }
+    // Fallback-name derivation: keep the name the user explicitly selected
+    // (including a symlinked directory's own name), but "." / ".." carry no
+    // name at all — resolve those through the real root, or `publish .` would
+    // fall back to a clip literally named "." (name is the org-wide upsert key).
+    const rawName = basename(directory);
+    const directoryName = rawName === '' || rawName === '.' || rawName === '..' ? basename(root) : rawName;
+    return { manifest, files, directoryName };
+}
+const PUBLISHED_METADATA_KEYS = ['type', 'domain', 'requires_login', 'server', 'auth'];
+/**
+ * The explicit `type` values the platform recognizes. Absent/null means
+ * browser (the original clip.json shape predates the field), so only a
+ * declared-but-unrecognized value is refused — locally, before any request
+ * leaves the machine, mirroring the server's publish gate. "clip" gets a named
+ * hint because every Pinix v2 package manifest declares it, and a v2 manifest
+ * republished as-is used to be classified as an MCP clip downstream.
+ */
+function assertPublishableManifestType(manifest) {
+    const type = manifest.type;
+    if (type == null || type === 'browser' || type === 'mcp')
+        return;
+    const message = type === 'clip'
+        ? 'manifest "type" "clip" is the legacy Pinix v2 package value — declare "browser" (or omit the field) for a browser clip, "mcp" for an MCP clip'
+        : `manifest "type" must be "browser" or "mcp" (or omitted for a browser clip); got ${JSON.stringify(type)}`;
+    throw new Error(`Invalid manifest: ${message}`);
+}
+/**
+ * The manifest subset that gets stored in the registry: the commands map plus
+ * the metadata keys the exec/display sides read. Mirrors the Edge CLI's
+ * buildPublishedManifest — local-only fields (name/version/visibility ride as
+ * top-level request fields) stay out of the stored manifest.
+ */
+export function buildPublishedManifest(manifest) {
+    assertPublishableManifestType(manifest);
+    // `||`, matching the Edge CLI exactly: a falsy non-object `commands` (a
+    // malformed manifest) normalizes to {} rather than being published as-is.
+    const published = { commands: manifest.commands || {} };
+    for (const key of PUBLISHED_METADATA_KEYS) {
+        if (manifest[key] !== undefined)
+            published[key] = manifest[key];
+    }
+    return published;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/cli",
-  "version": "1.52.0",
+  "version": "1.52.2",
   "description": "CLI client for Parall — universal agent & human access to Parall API",
   "license": "MIT",
   "repository": {
@@ -36,14 +36,14 @@
     "diff": "^8.0.3",
     "js-yaml": "^4.1.0",
     "zod": "^4.3.6",
-    "@parall/sdk": "1.52.0",
-    "@parall/agent-core": "1.52.0"
+    "@parall/agent-core": "1.52.2",
+    "@parall/sdk": "1.52.2"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0",
-    "@parall/agent-core": "1.52.0"
+    "@parall/agent-core": "1.52.2"
   },
   "scripts": {
     "build": "tsc",

package/dist/lib/clip-invoke.d.ts

@@ -1,45 +0,0 @@
-import type { InvokeClipRequest, InvokeClipResponse, ParallClient } from '@parall/sdk';
-/**
- * Hosted browser activation wait — CLI-side bounded retry for `clip invoke`.
- *
- * A clip bound to a `placement=hosted` BrowserProfile whose pod is cold returns
- * 503 BROWSER_PROFILE_ACTIVATING from the invoke pre-flight: the controller is
- * spawning + registering the pod, and the clip command has NOT been dispatched
- * yet, so retrying the same request cannot double-execute anything. This module
- * absorbs that one precise error so a single `parall clip invoke` rides through
- * cold start instead of forcing the caller (agent or human) into a blind
- * retry loop.
- *
- * Deliberately NOT in the SDK: `invokeClip()` keeps its throw-on-503 semantics
- * for every other consumer; only the CLI invoke behavior waits.
- */
-/** Total activation wait budget. Independent of the clip command --timeout:
- *  each attempt keeps its own full command timeout, so worst-case wall clock is
- *  roughly this budget plus one command timeout. */
-export declare const ACTIVATION_WAIT_BUDGET_MS = 60000;
-/** Backoff schedule between activation retries; the last entry repeats. */
-export declare const ACTIVATION_BACKOFF_MS: number[];
-/** Injectable time hooks so tests never really sleep. */
-export type ActivationWaitHooks = {
-    sleep?: (ms: number) => Promise<void>;
-    now?: () => number;
-};
-/**
- * The ONLY retryable error: a typed ApiError carrying exactly 503 +
- * BROWSER_PROFILE_ACTIVATING. Everything else — consent, permission, provider
- * offline/not-running, command errors, timeouts, other 5xx — means retrying is
- * either pointless or unsafe (the command may have been dispatched), so it
- * propagates unchanged on the first occurrence.
- */
-export declare function isActivationPending(err: unknown): boolean;
-/**
- * Invoke a clip, transparently absorbing the hosted-browser activation window.
- *
- * Retries the identical request while the server reports
- * BROWSER_PROFILE_ACTIVATING, backing off 500ms → 1s → 2s (capped) until the
- * 60s activation budget is spent. Once spent, the LAST typed ApiError is
- * rethrown as-is — status/code intact — so the printed error stays
- * machine-readable. Any other failure is rethrown immediately.
- */
-export declare function invokeClipAwaitingActivation(client: Pick<ParallClient, 'invokeClip'>, orgId: string, req: InvokeClipRequest, hooks?: ActivationWaitHooks): Promise<InvokeClipResponse>;
-//# sourceMappingURL=clip-invoke.d.ts.map

package/dist/lib/clip-invoke.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"clip-invoke.d.ts","sourceRoot":"","sources":["../../src/lib/clip-invoke.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGvF;;;;;;;;;;;;;GAaG;AAEH;;oDAEoD;AACpD,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD,2EAA2E;AAC3E,eAAO,MAAM,qBAAqB,UAAsB,CAAC;AAEzD,yDAAyD;AACzD,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB,CAAC;AAIF;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEzD;AAED;;;;;;;;GAQG;AACH,wBAAsB,4BAA4B,CAChD,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,EACxC,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,iBAAiB,EACtB,KAAK,CAAC,EAAE,mBAAmB,GAC1B,OAAO,CAAC,kBAAkB,CAAC,CAiB7B"}

package/dist/lib/clip-invoke.js

@@ -1,61 +0,0 @@
-import { ApiError } from '@parall/sdk';
-/**
- * Hosted browser activation wait — CLI-side bounded retry for `clip invoke`.
- *
- * A clip bound to a `placement=hosted` BrowserProfile whose pod is cold returns
- * 503 BROWSER_PROFILE_ACTIVATING from the invoke pre-flight: the controller is
- * spawning + registering the pod, and the clip command has NOT been dispatched
- * yet, so retrying the same request cannot double-execute anything. This module
- * absorbs that one precise error so a single `parall clip invoke` rides through
- * cold start instead of forcing the caller (agent or human) into a blind
- * retry loop.
- *
- * Deliberately NOT in the SDK: `invokeClip()` keeps its throw-on-503 semantics
- * for every other consumer; only the CLI invoke behavior waits.
- */
-/** Total activation wait budget. Independent of the clip command --timeout:
- *  each attempt keeps its own full command timeout, so worst-case wall clock is
- *  roughly this budget plus one command timeout. */
-export const ACTIVATION_WAIT_BUDGET_MS = 60_000;
-/** Backoff schedule between activation retries; the last entry repeats. */
-export const ACTIVATION_BACKOFF_MS = [500, 1_000, 2_000];
-const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-/**
- * The ONLY retryable error: a typed ApiError carrying exactly 503 +
- * BROWSER_PROFILE_ACTIVATING. Everything else — consent, permission, provider
- * offline/not-running, command errors, timeouts, other 5xx — means retrying is
- * either pointless or unsafe (the command may have been dispatched), so it
- * propagates unchanged on the first occurrence.
- */
-export function isActivationPending(err) {
-    return err instanceof ApiError && err.status === 503 && err.code === 'BROWSER_PROFILE_ACTIVATING';
-}
-/**
- * Invoke a clip, transparently absorbing the hosted-browser activation window.
- *
- * Retries the identical request while the server reports
- * BROWSER_PROFILE_ACTIVATING, backing off 500ms → 1s → 2s (capped) until the
- * 60s activation budget is spent. Once spent, the LAST typed ApiError is
- * rethrown as-is — status/code intact — so the printed error stays
- * machine-readable. Any other failure is rethrown immediately.
- */
-export async function invokeClipAwaitingActivation(client, orgId, req, hooks) {
-    const sleep = hooks?.sleep ?? realSleep;
-    const now = hooks?.now ?? Date.now;
-    const deadline = now() + ACTIVATION_WAIT_BUDGET_MS;
-    for (let attempt = 0;; attempt++) {
-        try {
-            return await client.invokeClip(orgId, req);
-        }
-        catch (err) {
-            if (!isActivationPending(err))
-                throw err;
-            const remaining = deadline - now();
-            if (remaining <= 0)
-                throw err;
-            const backoff = ACTIVATION_BACKOFF_MS[Math.min(attempt, ACTIVATION_BACKOFF_MS.length - 1)];
-            // Clamp to the remaining budget so the final sleep can't overrun it.
-            await sleep(Math.min(backoff, remaining));
-        }
-    }
-}