@parall/agent-core 1.42.1 → 1.43.0

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,MAAM,MAAM,UAAU,GAAG;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE,mFAAmF;IACnF,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,kBAAkB,EAAE,UAAU,EAAE,CAAC;IACjC,UAAU,EAAE,WAAW,EAAE,CAAC;IAC1B,oFAAoF;IACpF,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EACA,SAAS,GACT,MAAM,GACN,cAAc,GACd,cAAc,GACd,UAAU,GACV,kBAAkB,GAClB,iBAAiB,GACjB,UAAU,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,KAAK,CAAC;QAClB,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC,6BAA6B,CAAC,EAAE,MAAM,CAAC;IACvC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,qEAAqE;IACrE,6BAA6B,CAAC,EAAE,MAAM,CAAC;IACvC,yDAAyD;IACzD,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC;;wEAEoE;IACpE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;8EAC0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EACV,SAAS,GACT,eAAe,GACf,SAAS,GACT,cAAc,GACd,sBAAsB,GACtB,iBAAiB,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wGAAwG;IACxG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/agent-core",
-  "version": "1.42.1",
+  "version": "1.43.0",
   "description": "Shared agent runtime orchestration helpers for Parall",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
     "@opentelemetry/sdk-logs": "^0.57.0",
     "@opentelemetry/sdk-metrics": "^1.30.0",
     "@opentelemetry/sdk-trace-node": "^1.30.0",
-    "@parall/sdk": "1.42.1"
+    "@parall/sdk": "1.43.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/bin/channel-exec.ts

@@ -0,0 +1,262 @@
+// channel-exec — the short-lived exec form of the channel-capability
+// credential engine. Invoked by the pointer shims the materializer drops on
+// the capability PATH (e.g. `lark-cli` → `node <this file> --channel feishu
+// --bin lark-cli --skip-dir <shimDir> -- <args…>`): mints a fresh short-lived
+// token from the platform on EVERY call, injects it as the vendor CLI's own
+// documented env credentials, resolves the real binary past the shim
+// directory, and execs it with stdio passthrough.
+//
+// This is a process entry point, not a library — importing it runs main().
+// It lives inside @parall/agent-core so it ships atomically with the bridge
+// (image / daemon bundle), never depending on agent-writable install state.
+// Design: docs/engineering-design/agent-capability-fragments-design.md §5.1.
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { CHANNEL_POINTER_MAGIC } from '../channel-capability.js';
+import { ChannelTokenError, mintChannelToken } from '../channel-token.js';
+
+// The vendor binary each channel targets is fixed HERE, not taken from the
+// caller — channel-exec must never mint a token and hand it to a
+// caller-named program. `--bin` is deliberately not an argument, so a request
+// like `--channel feishu --bin evil` (with a tampered PATH) cannot redirect
+// the minted token to an attacker-chosen executable.
+const CHANNEL_BIN: Record<string, string> = { feishu: 'lark-cli' };
+
+interface ExecArgs {
+  channel: string;
+  skipDir: string;
+  rest: string[];
+}
+
+function fail(prefix: string, msg: string, code: number): never {
+  // Write to fd 2 SYNCHRONOUSLY: process.exit() right after an async
+  // process.stderr.write() can truncate the message when stderr is a pipe
+  // (notably on Windows) — and this path carries the install hint / revocation
+  // message the agent must relay to the user. writeSync flushes before exit;
+  // exit still runs so fail() keeps its `never` contract.
+  try {
+    fs.writeSync(2, `${prefix}: ${msg}\n`);
+  } catch {
+    // best-effort — still exit with the intended status
+  }
+  process.exit(code);
+}
+
+function parseArgs(argv: string[]): ExecArgs {
+  const out: ExecArgs = { channel: '', skipDir: '', rest: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') {
+      out.rest = argv.slice(i + 1);
+      break;
+    }
+    if (a === '--channel') out.channel = argv[++i] ?? '';
+    else if (a === '--skip-dir') out.skipDir = argv[++i] ?? '';
+    else fail('channel-exec', `unknown argument ${a}`, 2);
+  }
+  if (!out.channel) {
+    fail('channel-exec', 'usage: channel-exec --channel <type> [--skip-dir <dir>] -- <args…>', 2);
+  }
+  return out;
+}
+
+// A candidate that carries the pointer magic in its head is one of OUR
+// pointers (or a stray copy of one) — never the real vendor binary. This
+// makes self-recursion structurally impossible even when the skip-dir hint
+// is wrong or the pointer got copied elsewhere on PATH.
+function isCapabilityPointer(candidate: string): boolean {
+  try {
+    const fd = fs.openSync(candidate, 'r');
+    try {
+      const buf = Buffer.alloc(256);
+      const n = fs.readSync(fd, buf, 0, buf.length, 0);
+      return buf.toString('utf8', 0, n).includes(CHANNEL_POINTER_MAGIC);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return false;
+  }
+}
+
+// Resolve the REAL vendor binary along PATH, skipping the shim's own
+// directory (realpath comparison, so symlinked layouts don't fool it).
+function resolveRealBin(bin: string, skipDir: string): string | null {
+  const isWin = process.platform === 'win32';
+  // npm on Windows installs `<bin>` (sh) + `<bin>.cmd` + `<bin>.ps1`; the sh
+  // file is not spawnable by CreateProcess, so prefer the .cmd/.exe forms.
+  const exts = isWin ? ['.cmd', '.exe', '.bat'] : [''];
+  let skipReal: string | null = null;
+  if (skipDir) {
+    try {
+      skipReal = fs.realpathSync(skipDir);
+    } catch {
+      skipReal = null;
+    }
+  }
+  for (const dir of (process.env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    let real: string;
+    try {
+      real = fs.realpathSync(dir);
+    } catch {
+      continue;
+    }
+    if (skipReal && real === skipReal) continue;
+    for (const ext of exts) {
+      const candidate = path.join(dir, bin + ext);
+      try {
+        if (fs.statSync(candidate).isFile() && !isCapabilityPointer(candidate)) return candidate;
+      } catch {
+        // keep scanning
+      }
+    }
+  }
+  return null;
+}
+
+// The exact lark-cli env credentials the broker OWNS: the values it injects
+// plus the ambient auth inputs it must strip so nothing widens the identity
+// beyond the minted grant. Scrubbing is confined to THESE names — never a
+// blanket LARKSUITE_CLI_* wipe — so legitimate operator controls
+// (LARKSUITE_CLI_CONFIG_DIR / LOG_DIR / CONTENT_SAFETY_MODE / …) survive.
+const FEISHU_OWNED_ENV = [
+  // injected (canonical values set below)
+  'LARKSUITE_CLI_APP_ID',
+  'LARKSUITE_CLI_BRAND',
+  'LARKSUITE_CLI_TENANT_ACCESS_TOKEN',
+  'LARKSUITE_CLI_DEFAULT_AS',
+  'LARKSUITE_CLI_STRICT_MODE',
+  // ambient auth bypass inputs that must not reach the child
+  'LARKSUITE_CLI_APP_SECRET',
+  'LARKSUITE_CLI_USER_ACCESS_TOKEN',
+  'LARKSUITE_CLI_AUTH_PROXY',
+  'LARKSUITE_CLI_PROXY_KEY',
+];
+
+// Per-channel env injection: the ONLY channel-specific knowledge in this
+// entry.
+function buildChildEnv(
+  channel: string,
+  minted: { app_id: string; brand: string; token: string },
+): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  if (channel === 'feishu') {
+    // Delete the broker-owned names case-insensitively: Windows env keys are
+    // case-insensitive and a plain-object spread keeps the host's casing, so
+    // an uppercase-only delete would miss e.g. `Larksuite_Cli_Auth_Proxy` (a
+    // bypass leak) or leave a stale-cased duplicate shadowing the injected
+    // token. Non-owned LARKSUITE_CLI_* operator settings are left untouched.
+    const owned = new Set(FEISHU_OWNED_ENV);
+    for (const key of Object.keys(env)) {
+      if (owned.has(key.toUpperCase())) delete env[key];
+    }
+    env.LARKSUITE_CLI_APP_ID = minted.app_id;
+    env.LARKSUITE_CLI_BRAND = minted.brand || 'feishu';
+    env.LARKSUITE_CLI_TENANT_ACCESS_TOKEN = minted.token;
+    // Bot lock: the credential is the app's, not a human's.
+    env.LARKSUITE_CLI_DEFAULT_AS = 'bot';
+    env.LARKSUITE_CLI_STRICT_MODE = 'bot';
+    return env;
+  }
+  fail('channel-exec', `unsupported channel type "${channel}"`, 2);
+}
+
+// Windows argv-preserving quoting, ported from cross-spawn (the npm-ecosystem
+// standard for correctly launching .cmd shims). Node's `shell: true` does NOT
+// escape arguments — it concatenates them, so JSON/message args split or
+// inject on cmd.exe — and CreateProcess cannot run a .cmd directly. The proven
+// path is cmd.exe /d /s /c with each token escaped for BOTH the CreateProcess
+// argv layer and the cmd.exe metachar layer (double-escaped because a .cmd
+// re-parses). Still Windows-only and NO Windows CI: validate on a real Windows
+// host before the first Windows selfhost user (the round-trip tests lock the
+// escaping rules, not the live cmd.exe behavior).
+// cmd.exe metacharacters, matching cross-spawn's metaCharsRegExp (v7.0.6). ONE
+// set shared by BOTH the command and the arguments — cross-spawn uses a single
+// regex for both, and a split set is a real correctness hole: a metachar
+// caret-escaped in the command path but left bare in an argument (or the
+// reverse) survives only one of cmd.exe's two parse passes. Includes the
+// separators (space, `;`, `,`) and glob chars (`*`, `?`) so a quoted argument's
+// separators are still neutralized for the `.cmd` re-parse, exactly as
+// cross-spawn does.
+const CMD_META_CHARS = /([()\][%!^"`<>&|;, *?])/g;
+
+function escapeCmdArgument(arg: string): string {
+  let out = `${arg}`;
+  // Double backslashes before a quote, and trailing backslashes, then wrap.
+  out = out.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, '$1$1');
+  out = `"${out}"`;
+  // cmd metachars, escaped twice (the .cmd forwarder re-parses).
+  out = out.replace(CMD_META_CHARS, '^$1').replace(CMD_META_CHARS, '^$1');
+  return out;
+}
+
+function escapeCmdCommand(command: string): string {
+  return command.replace(CMD_META_CHARS, '^$1');
+}
+
+function runReal(realBin: string, args: string[], env: NodeJS.ProcessEnv, prefix: string): never {
+  const isWinScript = process.platform === 'win32' && /\.(cmd|bat)$/i.test(realBin);
+  const result = isWinScript
+    ? spawnSync(
+        process.env.comspec || 'cmd.exe',
+        [
+          '/d',
+          '/s',
+          '/c',
+          `"${[escapeCmdCommand(realBin), ...args.map(escapeCmdArgument)].join(' ')}"`,
+        ],
+        { stdio: 'inherit', env, windowsVerbatimArguments: true },
+      )
+    : spawnSync(realBin, args, { stdio: 'inherit', env });
+  if (result.error) {
+    fail(prefix, `failed to run ${realBin}: ${String(result.error)}`, 1);
+  }
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+    // Unreachable in practice; satisfy the `never` contract if the signal is trapped.
+    process.exit(1);
+  }
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+// Exported for round-trip unit tests (Windows spawn can't run in CI).
+export { escapeCmdArgument, escapeCmdCommand };
+
+async function main(): Promise<void> {
+  const { channel, skipDir, rest } = parseArgs(process.argv.slice(2));
+  const bin = CHANNEL_BIN[channel];
+  if (!bin) fail('channel-exec', `unsupported channel type "${channel}"`, 2);
+  const prefix = bin;
+
+  let minted: Awaited<ReturnType<typeof mintChannelToken>>;
+  try {
+    minted = await mintChannelToken(channel, process.env);
+  } catch (err) {
+    if (err instanceof ChannelTokenError) fail(prefix, err.message, 1);
+    fail(prefix, String(err), 1);
+  }
+
+  const real = resolveRealBin(bin, skipDir);
+  if (!real) {
+    const hint =
+      channel === 'feishu'
+        ? 'Install it once with:\n  npm i -g @larksuite/cli && npx skills add larksuite/cli -y -g'
+        : 'Install it and retry.';
+    fail(prefix, `the ${bin} binary is not installed. ${hint}`, 127);
+  }
+
+  runReal(real, rest, buildChildEnv(channel, minted), prefix);
+}
+
+// Run main() only when invoked AS A PROGRAM (the pointer shim runs
+// `node <this>`), not when a test imports this module for the escape helpers.
+// Holds in both layouts: npm (argv[1] = channel-exec.js) and bundle
+// (argv[1] = parall-channel-exec.js, which is also this module's own url).
+const invokedPath = process.argv[1];
+if (invokedPath && import.meta.url === pathToFileURL(invokedPath).href) {
+  void main();
+}

package/src/channel-capability.ts

@@ -0,0 +1,187 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { GatewayLogger } from './dispatch-adapter.js';
+import type { AgentCapability } from './platform-config.js';
+
+// Runtime-side materializer for channel capabilities — a pure PLACEMENT
+// layer. The server declares WHAT the agent has (agents.capabilities[]);
+// the credential logic lives in this package's channel-exec entry
+// (bin/channel-exec.ts, reusing channel-token.ts); this module only drops
+// constant POINTER shims onto the capability PATH so the vendor command name
+// (e.g. `lark-cli`, which the official skills invoke directly) routes into
+// that entry. Pointers reference channel-exec by IN-PACKAGE ABSOLUTE PATH —
+// no PATH lookup, no dependence on agent-writable install state; the engine
+// ships atomically with the bridge.
+//
+// Revocation keeps the pointer in place (nothing to remove): the pointer's
+// content is independent of grant state, and revocation semantics are
+// enforced by the platform mint endpoint (403 with an agent-readable
+// message). Deleting would let PATH fall through to a directly-installed
+// real CLI past the mint gate — the failure mode the old deny-stub existed
+// to prevent; a constant pointer prevents it structurally.
+// Design: docs/engineering-design/agent-capability-fragments-design.md §5.1.
+
+export const CAPABILITY_FEISHU_CLI = 'feishu-cli';
+
+// Marker embedded in every generated pointer. channel-exec skips any PATH
+// candidate whose head carries it, so a pointer (or a stray copy of one) can
+// never be mistaken for the real vendor binary — self-recursion is
+// structurally impossible even if the skip-dir hint is wrong.
+export const CHANNEL_POINTER_MAGIC = 'parall channel capability pointer';
+
+// SSOT for the shim directory: bridges prepend this to the child PATH once,
+// unconditionally — the directory is constant, its content tracks grants, so
+// a grant reaches even long-lived subprocesses (the shell re-resolves PATH
+// per command) without any respawn.
+export function capabilityBinDir(stateDir: string): string {
+  return path.join(stateDir, 'bin');
+}
+
+// Absolute path of the channel-exec entry, resolved across BOTH distribution
+// layouts — mirroring the daemon's resolveBbBrowserDaemonPath:
+//   - npm / hosted image: agent-core's dist tree exists on disk →
+//     ./bin/channel-exec.js sits under this module's dir.
+//   - standalone bundle (@parall/daemon / CDN self-update / desktop): esbuild
+//     flattens this module INTO bundle/parall-claude-agent.js, so ./bin/…
+//     doesn't exist; the bundle ships parall-channel-exec.js as a sibling flat
+//     artifact (scripts/bundle-daemon.mjs), resolved next to this file.
+// Prefer the sibling (bundle) and fall through to the in-package path (dev /
+// npm), like the bb-browser resolver — the two candidates are mutually
+// exclusive so order only affects which stat wins in the impossible case that
+// both exist.
+export function channelExecEntryPath(): string {
+  const selfDir = path.dirname(fileURLToPath(import.meta.url));
+  const sibling = path.join(selfDir, 'parall-channel-exec.js');
+  if (fs.existsSync(sibling)) return sibling;
+  return fileURLToPath(new URL('./bin/channel-exec.js', import.meta.url));
+}
+
+/**
+ * Idempotently reconcile local capability pointers with the delivered
+ * capability list. Call at boot (after the first config fetch) and on every
+ * config refresh. Never throws — a pointer write failure must not take down
+ * a config refresh (the capability simply stays unusable until the next pass).
+ */
+export function materializeChannelCapabilities(
+  stateDir: string,
+  capabilities: AgentCapability[],
+  log?: GatewayLogger,
+): void {
+  try {
+    reconcileFeishuCli(stateDir, capabilities, log);
+  } catch (err) {
+    log?.warn(`channel capability materialization failed: ${String(err)}`);
+  }
+}
+
+function reconcileFeishuCli(
+  stateDir: string,
+  capabilities: AgentCapability[],
+  log?: GatewayLogger,
+): void {
+  const binDir = capabilityBinDir(stateDir);
+  const posixPath = path.join(binDir, 'lark-cli');
+  const granted = capabilities.some((c) => c.key === CAPABILITY_FEISHU_CLI);
+  const hadPointer = fs.existsSync(posixPath);
+
+  // Write/refresh pointers when GRANTED, or when a pointer already exists (a
+  // previously-granted, now-revoked agent). The refresh-on-revoke case is
+  // load-bearing for bundle self-update: the pointer embeds channel-exec's
+  // ABSOLUTE path, which resolves through the daemon's `current` symlink into
+  // a versioned dir; after an upgrade prunes the old version, a stale retained
+  // pointer would fail MODULE_NOT_FOUND instead of reaching the mint 403.
+  // Re-rendering every pass keeps the pointer aimed at the LIVE channel-exec,
+  // so a revoked agent still gets the self-explanatory 403. A NEVER-granted
+  // agent (no pointer) is left untouched — the operator's own lark-cli install
+  // stays clean.
+  if (!granted && !hadPointer) return;
+
+  fs.mkdirSync(binDir, { recursive: true });
+  const entry = channelExecEntryPath();
+  // The node binary is referenced by ABSOLUTE path (process.execPath), not the
+  // bare name `node`: packaged installs (desktop / daemon bundle) embed the
+  // runtime as `parall-node` with no plain `node` on PATH, so a bare `node`
+  // would die before channel-exec ever runs and break bundle parity at the
+  // last hop. process.execPath is the very node currently running the bridge —
+  // the parall-node in a bundle, the system node under npm.
+  const nodeExec = process.execPath;
+  writePointerIfChanged(posixPath, renderPosixPointer(nodeExec, entry, binDir, 'feishu'), log);
+  // Windows companion: cmd/PowerShell resolve executables via PATHEXT and
+  // ignore extensionless shebang files. (The agent's own Bash tool on Windows
+  // is git-bash, which uses the sh pointer above — the .cmd is the cmd/
+  // PowerShell fallback; its %* follows standard batch semantics, same as any
+  // npm-installed .cmd bin.)
+  writePointerIfChanged(
+    path.join(binDir, 'lark-cli.cmd'),
+    renderCmdPointer(nodeExec, entry, binDir, 'feishu'),
+    log,
+  );
+}
+
+function writePointerIfChanged(filePath: string, content: string, log?: GatewayLogger): void {
+  let existing: string | null = null;
+  try {
+    existing = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    existing = null;
+  }
+  if (existing !== content) {
+    fs.writeFileSync(filePath, content, { mode: 0o755 });
+    log?.info(`channel capability: pointer materialized (${path.basename(filePath)})`);
+  }
+  // Mode is enforced even when content is unchanged (a prior partial write
+  // or umask drift must not leave the pointer non-executable).
+  fs.chmodSync(filePath, 0o755);
+}
+
+// Pointer content is versioned HERE (never delivered by the server — config
+// carries declarations, not code). It embeds the entry's AND the bin dir's
+// absolute paths at write time — no $(dirname)/external commands (a minimal
+// PATH must not break the pointer), and the skip hint cannot drift. A
+// package upgrade that moves paths changes the rendered content, and the
+// boot-time materialize pass rewrites it (self-healing).
+// The target binary is NOT passed on the command line — channel-exec derives
+// it from the channel (feishu → lark-cli), so a caller cannot redirect the
+// minted token to a different program. binDir is still passed as the skip hint.
+export function renderPosixPointer(
+  nodeExecPath: string,
+  entryJsPath: string,
+  binDir: string,
+  channel: string,
+): string {
+  return [
+    '#!/bin/sh',
+    `# Generated by @parall/agent-core — ${CHANNEL_POINTER_MAGIC} (do not edit).`,
+    '# Credential + exec logic lives in the agent-core package; revocation is',
+    '# enforced by the platform mint endpoint, so this pointer stays constant.',
+    // Strip Node preload-hijack vars BEFORE launching node: NODE_OPTIONS
+    // (e.g. --require=/evil.js) and NODE_PATH would execute caller-supplied code
+    // at interpreter startup — BEFORE channel-exec's own env scrub, i.e. before
+    // the mint. The pointer is a platform-authored trust-boundary artifact whose
+    // whole job is a CONTROLLED launch of the broker (absolute node, magic
+    // guard, skip-dir); this closes the same env-hijack class for node startup
+    // that the absolute node path closes for PATH, keeping the launch deterministic.
+    'unset NODE_OPTIONS NODE_PATH',
+    // "$@" preserves argv exactly (this is the agent's main path via git-bash).
+    `exec "${nodeExecPath}" "${entryJsPath}" --channel ${channel} --skip-dir "${binDir}" -- "$@"`,
+    '',
+  ].join('\n');
+}
+
+export function renderCmdPointer(
+  nodeExecPath: string,
+  entryJsPath: string,
+  binDir: string,
+  channel: string,
+): string {
+  return [
+    '@echo off',
+    `rem Generated by @parall/agent-core - ${CHANNEL_POINTER_MAGIC} (do not edit).`,
+    // Clear Node preload-hijack vars before launching node (see the sh pointer).
+    'set "NODE_OPTIONS="',
+    'set "NODE_PATH="',
+    `"${nodeExecPath}" "${entryJsPath}" --channel ${channel} --skip-dir "${binDir}" -- %*`,
+    '',
+  ].join('\r\n');
+}

package/src/channel-token.ts

@@ -0,0 +1,92 @@
+// Channel-capability credential client — the ONE place that talks to the
+// platform mint endpoint. Consumed today by the short-lived exec form
+// (bin/channel-exec.ts); the future resident forms (proxy / mcp, hosted by
+// the bridge process) reuse this module so swimlane routing, error
+// presentation, and any future retry/telemetry policy stay single-sourced.
+// Design: docs/engineering-design/agent-capability-fragments-design.md §5.
+
+export interface MintedChannelToken {
+  channel_type: string;
+  token_type: string;
+  app_id: string;
+  brand: string;
+  token: string;
+  expires_at: string;
+}
+
+// Thrown for every mint failure; `message` is written for the AGENT to read
+// (and relay to the user when the platform says the capability is revoked).
+export class ChannelTokenError extends Error {}
+
+const MINT_TIMEOUT_MS = 10_000;
+
+/**
+ * Exchange the agent's channel grant for a short-lived provider token.
+ * Deliberately NO local caching at any layer here: the parall round trip is
+ * tens of ms (the expensive vendor exchange is absorbed by the server-side
+ * Redis cache), and every call re-passing the server gate is what makes
+ * revocation and re-credentialing bite on the very next invocation.
+ */
+export async function mintChannelToken(
+  channelType: string,
+  env: NodeJS.ProcessEnv,
+): Promise<MintedChannelToken> {
+  const apiUrl = (env.PRLL_API_URL || '').replace(/\/+$/, '');
+  const apiKey = env.PRLL_API_KEY || '';
+  const orgId = env.PRLL_ORG_ID || '';
+  if (!apiUrl || !apiKey || !orgId) {
+    throw new ChannelTokenError(
+      'PRLL_API_URL/PRLL_API_KEY/PRLL_ORG_ID missing from the environment',
+    );
+  }
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    Authorization: `Bearer ${apiKey}`,
+  };
+  // Swimlane routing must ride the mint request exactly like every SDK call —
+  // a bridge deployed in a PR swimlane mints against its own API/DB.
+  const swimlane = (env.PRLL_SWIMLANE_NAME || '').trim();
+  if (swimlane) headers['X-Prll-Swimlane'] = swimlane;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), MINT_TIMEOUT_MS);
+  let resp: Response;
+  try {
+    resp = await fetch(
+      `${apiUrl}/api/v1/orgs/${encodeURIComponent(orgId)}/agents/me/channel-token`,
+      {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ channel_type: channelType }),
+        signal: controller.signal,
+      },
+    );
+  } catch (err) {
+    throw new ChannelTokenError(
+      `could not reach the Parall platform to authenticate (${String(err)}); channel actions are unavailable right now`,
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (!resp.ok) {
+    let msg = `platform returned HTTP ${resp.status}`;
+    try {
+      const body = (await resp.json()) as { error?: { message?: string } };
+      if (body?.error?.message) msg = body.error.message;
+    } catch {
+      // non-JSON error body: keep the status-line message
+    }
+    throw new ChannelTokenError(msg);
+  }
+
+  // Validate every field the caller actually injects into the vendor CLI, not
+  // just `token`: a 2xx missing app_id/brand would otherwise launch the real
+  // CLI with an incomplete credential env and fail opaquely downstream.
+  const minted = (await resp.json()) as Partial<MintedChannelToken>;
+  const nonEmpty = (v: unknown): v is string => typeof v === 'string' && v.length > 0;
+  if (!minted || !nonEmpty(minted.token) || !nonEmpty(minted.app_id) || !nonEmpty(minted.brand)) {
+    throw new ChannelTokenError('platform returned an unusable token payload');
+  }
+  return minted as MintedChannelToken;
+}

package/src/event-format.ts

@@ -175,22 +175,27 @@ function buildSendMessageHint(event: ParallEvent): string {
   }
 
   if (event.type === 'channel_message') {
-    // Provider metadata is best-effort (the gateway's connection lookup can
-    // fail) — never instruct the agent to invoke a made-up clip alias.
-    const clipLabel = event.channelProvider
-      ? `the \`${event.channelProvider}\` clip's`
-      : "your channel provider clip's";
-    const apiLabel = event.channelProvider ?? 'external platform';
-    const target = event.channelExternalConversationId
-      ? `{"chat_id": "${event.channelExternalConversationId}", "text": "..."}`
-      : `{"chat_id": "<conversation id>", "text": "..."}`;
-    // Offer the in-thread alternative whenever the inbound message id is
-    // known — otherwise the hint nudges every threaded conversation toward a
-    // new top-level message.
-    const threadAlt = event.channelExternalMessageId
-      ? ` To reply in-thread to this specific message, use {"message_id": "${event.channelExternalMessageId}", "text": "..."} instead.`
-      : '';
-    return `\n<system-reminder>To reply, invoke ${clipLabel} \`send_message\` command with ${target} — your plain text output is NOT delivered to the external conversation.${threadAlt} The same clip's \`call\` command reaches the wider ${apiLabel} API when needed.</system-reminder>`;
+    // Single-path routing (multi-channel-architecture-design §6): with the
+    // `<provider>-cli` capability granted, the vendor CLI on PATH is THE
+    // reply path; without it there is no outbound path at all — say so
+    // instead of pointing at the retired provider clip.
+    // channelCliCapable alone decides: only feishu mints exist today, so a
+    // live grant implies Feishu even when the cosmetic provider-label lookup
+    // failed (event.channelProvider undefined).
+    if (event.channelCliCapable) {
+      const convRef = event.channelExternalConversationId
+        ? `chat_id "${event.channelExternalConversationId}"`
+        : 'the conversation id named in this event';
+      // Offer the in-thread alternative whenever the inbound message id is
+      // known — otherwise the hint nudges every threaded conversation toward
+      // a new top-level message.
+      const threadAlt = event.channelExternalMessageId
+        ? ` To reply threaded to this specific message, reference message_id "${event.channelExternalMessageId}".`
+        : '';
+      return `\n<system-reminder>To reply, use the official Feishu CLI on your PATH: send a message to ${convRef} with \`lark-cli im\` (see \`lark-cli im --help\` for send syntax; auth is provisioned automatically).${threadAlt} lark-cli is the ONLY outbound path — your plain text output is NOT delivered to the external conversation.</system-reminder>`;
+    }
+    const platform = event.channelProvider ?? 'the external platform';
+    return `\n<system-reminder>This message arrived from ${platform}, but outbound replies are currently disabled for this org (no channel capability granted). Do NOT attempt to reply on the external platform. If action is needed, surface it inside Parall (\`parall messages send\` / \`parall dm\`). Your plain text output is not delivered anywhere.</system-reminder>`;
   }
 
   if (event.type === 'external_trigger' || event.targetId.startsWith('xtr_')) {