@openparachute/agent 0.1.0

package/src/parachute/types.ts

@@ -0,0 +1,41 @@
+/**
+ * Types for the Parachute integration. Narrow on purpose — the broader
+ * Paraclaw types live in `src/types.ts` and `src/container-config.ts`.
+ */
+
+/**
+ * Scopes the vault recognizes. Format: `<service>:<resource>:<action>` per
+ * `parachute-patterns/patterns/oauth-scopes.md`. Today the vault ships with
+ * the action-only set; per-vault-name resource scoping (`vault:<name>:read`)
+ * is planned.
+ */
+export type VaultScope = 'vault:read' | 'vault:write' | 'vault:admin';
+
+/**
+ * What we record on the host side when a claw is attached to a vault. Lives
+ * in `groups/<folder>/parachute.json` (separate from `container.json` so
+ * upstream doesn't see Parachute fields it doesn't know how to handle).
+ */
+export interface VaultAttachment {
+  /** Vault base URL — `http://127.0.0.1:1940/vault/<name>` (no trailing slash, no `/mcp` suffix). */
+  vaultBaseUrl: string;
+  /** The scope granted to this claw. */
+  scope: VaultScope;
+  /** Token label registered with the vault — used for revocation, not the secret. */
+  tokenLabel: string;
+  /** When this attachment was created. */
+  attachedAt: string;
+}
+
+/**
+ * Options for `buildVaultMcpServer` — what the helper needs to produce a
+ * valid `McpServerConfig` HTTP entry.
+ */
+export interface BuildVaultMcpOpts {
+  /** Vault base URL (no `/mcp` suffix — we append it). */
+  vaultBaseUrl: string;
+  /** The `pvt_…` token to use as Bearer auth. */
+  vaultToken: string;
+  /** Optional: in-context guidance that lands in the composed CLAUDE.md. */
+  instructions?: string;
+}

package/src/parachute/vault-mcp.test.ts

@@ -0,0 +1,251 @@
+/**
+ * Tests for `localhostToContainerHost` + `rewriteMcpUrlsForContainer`.
+ *
+ * The translation runs at container-spawn time so an HTTP MCP server
+ * with a loopback URL on the host (`127.0.0.1`, `localhost`, …) becomes
+ * reachable from inside the Docker container, where loopback would
+ * otherwise resolve to the container itself.
+ */
+import fs from 'fs';
+import path from 'path';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { GROUPS_DIR } from '../config.js';
+import type { ContainerConfig } from '../container-config.js';
+import { listVaultAttachments, localhostToContainerHost, rewriteMcpUrlsForContainer } from './vault-mcp.js';
+
+describe('localhostToContainerHost', () => {
+  it('rewrites 127.0.0.1 → host.docker.internal, preserving port + path + scheme', () => {
+    expect(localhostToContainerHost('http://127.0.0.1:1940/vault/default/mcp')).toBe(
+      'http://host.docker.internal:1940/vault/default/mcp',
+    );
+  });
+
+  it('rewrites localhost', () => {
+    expect(localhostToContainerHost('http://localhost:1942/notes/api')).toBe(
+      'http://host.docker.internal:1942/notes/api',
+    );
+  });
+
+  it('rewrites 0.0.0.0 (treat as loopback for our purposes)', () => {
+    expect(localhostToContainerHost('http://0.0.0.0:1940/mcp')).toBe('http://host.docker.internal:1940/mcp');
+  });
+
+  it('rewrites IPv6 [::1]', () => {
+    expect(localhostToContainerHost('http://[::1]:1940/mcp')).toBe('http://host.docker.internal:1940/mcp');
+  });
+
+  it('rewrites localhost.localdomain', () => {
+    expect(localhostToContainerHost('http://localhost.localdomain:1940/mcp')).toBe(
+      'http://host.docker.internal:1940/mcp',
+    );
+  });
+
+  it('rewrites https scheme + preserves query string', () => {
+    expect(localhostToContainerHost('https://127.0.0.1:8443/mcp?session=abc')).toBe(
+      'https://host.docker.internal:8443/mcp?session=abc',
+    );
+  });
+
+  it('passes through tailnet hosts unchanged', () => {
+    const url = 'https://parachute.taildf9ce2.ts.net/vault/default/mcp';
+    expect(localhostToContainerHost(url)).toBe(url);
+  });
+
+  it('passes through public domains unchanged', () => {
+    const url = 'https://api.example.com/mcp';
+    expect(localhostToContainerHost(url)).toBe(url);
+  });
+
+  it('passes through LAN IPs unchanged (Docker bridge can route them)', () => {
+    expect(localhostToContainerHost('http://192.168.1.5:1940/mcp')).toBe('http://192.168.1.5:1940/mcp');
+    expect(localhostToContainerHost('http://10.0.0.5/mcp')).toBe('http://10.0.0.5/mcp');
+  });
+
+  it('passes through host.docker.internal (already translated)', () => {
+    const url = 'http://host.docker.internal:1940/mcp';
+    expect(localhostToContainerHost(url)).toBe(url);
+  });
+
+  it('returns malformed URL unchanged', () => {
+    expect(localhostToContainerHost('not-a-url')).toBe('not-a-url');
+    expect(localhostToContainerHost('')).toBe('');
+  });
+});
+
+describe('rewriteMcpUrlsForContainer', () => {
+  function baseConfig(): ContainerConfig {
+    return {
+      mcpServers: {},
+      packages: { apt: [], npm: [] },
+      additionalMounts: [],
+      skills: 'all',
+    };
+  }
+
+  it('rewrites URL on http MCP entries, leaves stdio entries alone', () => {
+    const cfg: ContainerConfig = {
+      ...baseConfig(),
+      mcpServers: {
+        'parachute-vault': {
+          type: 'http',
+          url: 'http://127.0.0.1:1940/vault/default/mcp',
+          headers: { Authorization: 'Bearer pvt_test' },
+        },
+        'local-tool': {
+          type: 'stdio',
+          command: 'node',
+          args: ['/app/tool.js'],
+        },
+      },
+    };
+
+    const out = rewriteMcpUrlsForContainer(cfg);
+
+    expect(out.mcpServers['parachute-vault']).toMatchObject({
+      type: 'http',
+      url: 'http://host.docker.internal:1940/vault/default/mcp',
+      headers: { Authorization: 'Bearer pvt_test' },
+    });
+    expect(out.mcpServers['local-tool']).toEqual({
+      type: 'stdio',
+      command: 'node',
+      args: ['/app/tool.js'],
+    });
+  });
+
+  it('does not mutate the input config', () => {
+    const cfg: ContainerConfig = {
+      ...baseConfig(),
+      mcpServers: {
+        v: { type: 'http', url: 'http://127.0.0.1:1940/mcp' },
+      },
+    };
+    const before = JSON.stringify(cfg);
+    rewriteMcpUrlsForContainer(cfg);
+    expect(JSON.stringify(cfg)).toBe(before);
+  });
+
+  it('passes already-tailnet entries through unchanged', () => {
+    const cfg: ContainerConfig = {
+      ...baseConfig(),
+      mcpServers: {
+        v: { type: 'http', url: 'https://parachute.taildf9ce2.ts.net/vault/default/mcp' },
+      },
+    };
+    const out = rewriteMcpUrlsForContainer(cfg);
+    expect((out.mcpServers.v as { url: string }).url).toBe('https://parachute.taildf9ce2.ts.net/vault/default/mcp');
+  });
+
+  it('handles multiple http entries independently', () => {
+    const cfg: ContainerConfig = {
+      ...baseConfig(),
+      mcpServers: {
+        vault: { type: 'http', url: 'http://127.0.0.1:1940/vault/default/mcp' },
+        notes: { type: 'http', url: 'http://localhost:1942/notes/mcp' },
+        public: { type: 'http', url: 'https://api.example.com/mcp' },
+      },
+    };
+    const out = rewriteMcpUrlsForContainer(cfg);
+    expect((out.mcpServers.vault as { url: string }).url).toBe('http://host.docker.internal:1940/vault/default/mcp');
+    expect((out.mcpServers.notes as { url: string }).url).toBe('http://host.docker.internal:1942/notes/mcp');
+    expect((out.mcpServers.public as { url: string }).url).toBe('https://api.example.com/mcp');
+  });
+});
+
+describe('listVaultAttachments', () => {
+  const created: string[] = [];
+
+  function makeGroup(folder: string, parachuteJson: object | null): string {
+    const dir = path.join(GROUPS_DIR, folder);
+    fs.mkdirSync(dir, { recursive: true });
+    if (parachuteJson !== null) {
+      fs.writeFileSync(path.join(dir, 'parachute.json'), JSON.stringify(parachuteJson, null, 2));
+    }
+    created.push(dir);
+    return folder;
+  }
+
+  afterEach(() => {
+    while (created.length > 0) {
+      const dir = created.pop()!;
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('returns one entry per (folder, mcpName) for folders with attachments', () => {
+    const a = makeGroup(`vmtest-a-${Date.now()}`, {
+      vault: {
+        'parachute-vault': {
+          vaultBaseUrl: 'https://h/vault/work',
+          scope: 'vault:read',
+          tokenLabel: 'claw-a',
+          attachedAt: '2026-04-29T00:00:00Z',
+        },
+      },
+    });
+    const b = makeGroup(`vmtest-b-${Date.now()}`, {
+      vault: {
+        'parachute-vault': {
+          vaultBaseUrl: 'https://h/vault/personal',
+          scope: 'vault:write',
+          tokenLabel: 'claw-b',
+          attachedAt: '2026-04-29T00:00:00Z',
+        },
+      },
+    });
+    const entries = listVaultAttachments([a, b]);
+    expect(entries).toHaveLength(2);
+    expect(entries.find((e) => e.folder === a)?.attachment.tokenLabel).toBe('claw-a');
+    expect(entries.find((e) => e.folder === b)?.attachment.tokenLabel).toBe('claw-b');
+  });
+
+  it('skips folders without parachute.json (forgiveness for unattached groups)', () => {
+    const a = makeGroup(`vmtest-noattach-${Date.now()}`, null);
+    const b = makeGroup(`vmtest-attach-${Date.now()}`, {
+      vault: {
+        'parachute-vault': {
+          vaultBaseUrl: 'https://h/vault/work',
+          scope: 'vault:read',
+          tokenLabel: 'claw-x',
+          attachedAt: '2026-04-29T00:00:00Z',
+        },
+      },
+    });
+    const entries = listVaultAttachments([a, b]);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]!.folder).toBe(b);
+  });
+
+  it('silently skips malformed parachute.json — never throws', () => {
+    const folder = `vmtest-bad-${Date.now()}`;
+    const dir = path.join(GROUPS_DIR, folder);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'parachute.json'), 'not json {{{');
+    created.push(dir);
+    expect(listVaultAttachments([folder])).toEqual([]);
+  });
+
+  it('returns one entry per mcpName when a folder has multiple attachments', () => {
+    const folder = makeGroup(`vmtest-multi-${Date.now()}`, {
+      vault: {
+        'parachute-vault': {
+          vaultBaseUrl: 'https://h/vault/work',
+          scope: 'vault:read',
+          tokenLabel: 'claw-work',
+          attachedAt: '2026-04-29T00:00:00Z',
+        },
+        'parachute-vault-personal': {
+          vaultBaseUrl: 'https://h/vault/personal',
+          scope: 'vault:write',
+          tokenLabel: 'claw-personal',
+          attachedAt: '2026-04-29T00:00:00Z',
+        },
+      },
+    });
+    const entries = listVaultAttachments([folder]);
+    expect(entries).toHaveLength(2);
+    expect(entries.map((e) => e.mcpName).sort()).toEqual(['parachute-vault', 'parachute-vault-personal']);
+  });
+});

package/src/parachute/vault-mcp.ts

@@ -0,0 +1,232 @@
+/**
+ * Helpers for attaching a Parachute Vault as an MCP server to a Paraclaw
+ * agent group.
+ *
+ * The vault MCP is HTTP-transport (`type: 'http'` + `url` + `Authorization`
+ * header). Attaching writes the entry into the group's `container.json`
+ * `mcpServers.<name>` slot and persists the attach record to a sibling
+ * `parachute.json` so we can list/detach later without re-asking for
+ * configuration.
+ */
+import fs from 'fs';
+import path from 'path';
+
+import { GROUPS_DIR } from '../config.js';
+import type { McpServerConfig, HttpMcpServerConfig, ContainerConfig } from '../container-config.js';
+import { readContainerConfig, writeContainerConfig } from '../container-config.js';
+import type { BuildVaultMcpOpts, VaultAttachment, VaultScope } from './types.js';
+
+/** Default name under which we register the vault MCP server. */
+export const DEFAULT_VAULT_MCP_NAME = 'parachute-vault';
+
+/** Path to the per-group Parachute attachment record. */
+function parachuteJsonPath(folder: string): string {
+  return path.join(GROUPS_DIR, folder, 'parachute.json');
+}
+
+/**
+ * Build the `McpServerConfig` for a vault attach. Pure — does not touch
+ * disk. The result is suitable for writing into `container.json`'s
+ * `mcpServers.<name>` slot.
+ */
+export function buildVaultMcpServer(opts: BuildVaultMcpOpts): HttpMcpServerConfig {
+  const baseUrl = opts.vaultBaseUrl.replace(/\/+$/, '');
+  return {
+    type: 'http',
+    url: `${baseUrl}/mcp`,
+    headers: {
+      Authorization: `Bearer ${opts.vaultToken}`,
+    },
+    instructions: opts.instructions,
+  };
+}
+
+/**
+ * Hostnames that point at "this machine" from outside a container, but
+ * inside a container point at the container itself — so an MCP server on
+ * the host is unreachable. Rewrite to `host.docker.internal`, which Docker
+ * Desktop / OrbStack expose natively on macOS+Windows. On Linux, paraclaw
+ * already passes `--add-host=host.docker.internal:host-gateway` to every
+ * `docker run` (`src/container-runtime.ts:hostGatewayArgs`), so the same
+ * hostname resolves there too.
+ *
+ * The point of this rewrite happening at *container-spawn* time (rather
+ * than persisted on disk) is so the on-disk `container.json` keeps the
+ * operator-facing URL — what they typed, what the UI displays. The
+ * container sees a derived copy with loopback addresses translated.
+ *
+ * Non-loopback hostnames (LAN IPs, public domains, tailnet hosts) pass
+ * through unchanged: they're already container-reachable via Docker's
+ * bridge or the host network.
+ */
+const CONTAINER_HOST_NAME = 'host.docker.internal';
+const LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '0.0.0.0', '::1', 'localhost.localdomain']);
+
+export function localhostToContainerHost(url: string): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    // Not a parseable URL — pass through unchanged. Caller will see the
+    // same connection error they would have anyway.
+    return url;
+  }
+  // URL canonicalizes `[::1]` to `[::1]` with brackets; strip for compare.
+  const hostname = parsed.hostname.replace(/^\[(.+)\]$/, '$1');
+  if (LOOPBACK_HOSTNAMES.has(hostname)) {
+    parsed.hostname = CONTAINER_HOST_NAME;
+    return parsed.toString();
+  }
+  return url;
+}
+
+/**
+ * Apply `localhostToContainerHost` to every HTTP MCP entry in a container
+ * config, returning a deep-cloned copy. The input config is left intact —
+ * use this when preparing a per-spawn copy of `container.json` to mount
+ * into a container without modifying what's persisted on disk.
+ */
+export function rewriteMcpUrlsForContainer(config: ContainerConfig): ContainerConfig {
+  // Structured clone is fine here: ContainerConfig is JSON-shaped.
+  const clone = JSON.parse(JSON.stringify(config)) as ContainerConfig;
+  for (const [name, entry] of Object.entries(clone.mcpServers)) {
+    if (entry && typeof entry === 'object' && 'type' in entry && entry.type === 'http' && 'url' in entry) {
+      const httpEntry = entry as HttpMcpServerConfig;
+      httpEntry.url = localhostToContainerHost(httpEntry.url);
+      clone.mcpServers[name] = httpEntry;
+    }
+  }
+  return clone;
+}
+
+export interface AttachVaultOpts {
+  /** Group folder name (matches `groups/<folder>`). */
+  folder: string;
+  /** Vault base URL, no trailing slash, no `/mcp` suffix. */
+  vaultBaseUrl: string;
+  /** The `pvt_…` token to bake into the MCP entry. */
+  vaultToken: string;
+  /** Scope this token was minted at — recorded in parachute.json for visibility. */
+  scope: VaultScope;
+  /** Token label (matches what's registered with the vault). */
+  tokenLabel: string;
+  /** Optional MCP name override. Defaults to `parachute-vault`. */
+  mcpName?: string;
+  /** Optional in-context instructions for the agent. */
+  instructions?: string;
+}
+
+/**
+ * Attach a vault to an agent group. Idempotent — re-attaching with the same
+ * `mcpName` updates the entry in place.
+ */
+export function attachVaultToGroup(opts: AttachVaultOpts): void {
+  const name = opts.mcpName ?? DEFAULT_VAULT_MCP_NAME;
+  const groupPath = path.join(GROUPS_DIR, opts.folder);
+  if (!fs.existsSync(groupPath)) {
+    throw new Error(`agent group folder not found: ${groupPath}`);
+  }
+
+  const cfg: ContainerConfig = readContainerConfig(opts.folder);
+  const mcpEntry: McpServerConfig = buildVaultMcpServer({
+    vaultBaseUrl: opts.vaultBaseUrl,
+    vaultToken: opts.vaultToken,
+    instructions: opts.instructions,
+  });
+  cfg.mcpServers[name] = mcpEntry;
+  writeContainerConfig(opts.folder, cfg);
+
+  const attachment: VaultAttachment = {
+    vaultBaseUrl: opts.vaultBaseUrl.replace(/\/+$/, ''),
+    scope: opts.scope,
+    tokenLabel: opts.tokenLabel,
+    attachedAt: new Date().toISOString(),
+  };
+  fs.writeFileSync(parachuteJsonPath(opts.folder), JSON.stringify({ vault: { [name]: attachment } }, null, 2) + '\n');
+}
+
+/**
+ * Read the Parachute attach record for a group, if any. Returns null when
+ * the file doesn't exist (group was never attached, or attached pre-record).
+ */
+export function readVaultAttachment(folder: string, mcpName = DEFAULT_VAULT_MCP_NAME): VaultAttachment | null {
+  const p = parachuteJsonPath(folder);
+  if (!fs.existsSync(p)) return null;
+  try {
+    const raw = JSON.parse(fs.readFileSync(p, 'utf8')) as {
+      vault?: Record<string, VaultAttachment>;
+    };
+    return raw.vault?.[mcpName] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read every vault attachment record across the given folders. Used by the
+ * `/agent/vaults` UI to compute "this token is attached to these groups" by
+ * matching `tokenLabel` against the vault's listed tokens.
+ *
+ * Returns one entry per (folder, mcpName) — a single group can have multiple
+ * attachments under different MCP names, though in practice we only use
+ * `parachute-vault`. Folders without a parachute.json or with malformed JSON
+ * are silently skipped (same forgiveness as `readVaultAttachment`).
+ */
+export interface VaultAttachmentEntry {
+  folder: string;
+  mcpName: string;
+  attachment: VaultAttachment;
+}
+
+export function listVaultAttachments(folders: string[]): VaultAttachmentEntry[] {
+  const out: VaultAttachmentEntry[] = [];
+  for (const folder of folders) {
+    const p = parachuteJsonPath(folder);
+    if (!fs.existsSync(p)) continue;
+    let raw: { vault?: Record<string, VaultAttachment> };
+    try {
+      raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+    } catch {
+      continue;
+    }
+    if (!raw.vault) continue;
+    for (const [mcpName, attachment] of Object.entries(raw.vault)) {
+      out.push({ folder, mcpName, attachment });
+    }
+  }
+  return out;
+}
+
+/**
+ * Detach a vault from an agent group. Removes the MCP entry from
+ * `container.json` and the attach record from `parachute.json`. Does NOT
+ * revoke the vault token — caller is responsible for `parachute vault
+ * tokens revoke <label>` since revocation is one-way and we don't want a
+ * detach to silently nuke a token an operator might still want.
+ */
+export function detachVaultFromGroup(folder: string, mcpName = DEFAULT_VAULT_MCP_NAME): void {
+  const cfg = readContainerConfig(folder);
+  if (cfg.mcpServers[mcpName]) {
+    delete cfg.mcpServers[mcpName];
+    writeContainerConfig(folder, cfg);
+  }
+
+  const p = parachuteJsonPath(folder);
+  if (fs.existsSync(p)) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(p, 'utf8')) as {
+        vault?: Record<string, VaultAttachment>;
+      };
+      if (raw.vault?.[mcpName]) {
+        delete raw.vault[mcpName];
+        if (Object.keys(raw.vault).length === 0) {
+          fs.unlinkSync(p);
+        } else {
+          fs.writeFileSync(p, JSON.stringify(raw, null, 2) + '\n');
+        }
+      }
+    } catch {
+      // best-effort — don't fail detach on a malformed record
+    }
+  }
+}

package/src/platform-id.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'vitest';
+
+import { decodePlatformIdAs, encodePlatformId, namespacedPlatformId } from './platform-id.js';
+
+describe('encodePlatformId — v2 format', () => {
+  it('joins <channel>:<botId>:<native>', () => {
+    expect(encodePlatformId('telegram', '8792496425', '1190596288')).toBe('telegram:8792496425:1190596288');
+  });
+
+  it('preserves colons inside native (Discord guildId:channelId)', () => {
+    // Discord native ids are themselves colon-separated; the v2 encoder must
+    // not normalize them — splitting back out happens at the first two
+    // colons only.
+    expect(encodePlatformId('discord', 'bot123', 'guild999:chan111')).toBe('discord:bot123:guild999:chan111');
+  });
+
+  it('preserves @me prefix in DM native (Discord)', () => {
+    expect(encodePlatformId('discord', 'bot123', '@me:user456')).toBe('discord:bot123:@me:user456');
+  });
+
+  it('handles negative chat ids (Telegram groups)', () => {
+    // Telegram group chat ids start with a hyphen — the v2 form has to leave
+    // them untouched.
+    expect(encodePlatformId('telegram', '8792496425', '-100123456789')).toBe('telegram:8792496425:-100123456789');
+  });
+});
+
+describe('decodePlatformIdAs(prefixed, "v2")', () => {
+  it('parses v2 telegram form', () => {
+    expect(decodePlatformIdAs('telegram:8792496425:1190596288', 'v2')).toEqual({
+      channel: 'telegram',
+      botId: '8792496425',
+      native: '1190596288',
+    });
+  });
+
+  it('parses v2 discord with colon-bearing native', () => {
+    expect(decodePlatformIdAs('discord:bot123:guild999:chan111', 'v2')).toEqual({
+      channel: 'discord',
+      botId: 'bot123',
+      native: 'guild999:chan111',
+    });
+  });
+
+  it('parses v2 discord DM with @me prefix in native', () => {
+    expect(decodePlatformIdAs('discord:bot123:@me:user456', 'v2')).toEqual({
+      channel: 'discord',
+      botId: 'bot123',
+      native: '@me:user456',
+    });
+  });
+
+  it('returns botId=null for legacy v1 form (single colon only)', () => {
+    // v1 `telegram:<chatId>` cannot be safely upgraded by the decoder alone;
+    // the caller must check `botId === null` and either backfill or skip.
+    expect(decodePlatformIdAs('telegram:1190596288', 'v2')).toEqual({
+      channel: 'telegram',
+      botId: null,
+      native: '1190596288',
+    });
+  });
+
+  it('returns botId=null for empty / channel-only string', () => {
+    expect(decodePlatformIdAs('telegram', 'v2')).toEqual({
+      channel: 'telegram',
+      botId: null,
+      native: '',
+    });
+  });
+});
+
+describe('encode/decode round-trip', () => {
+  it.each([
+    ['telegram', '8792496425', '1190596288'],
+    ['telegram', '8792496425', '-100123456789'],
+    ['discord', 'bot123', 'guild999:chan111'],
+    ['discord', 'bot123', '@me:user456'],
+    ['slack', '123', 'C12345:thread:ts'],
+  ] as const)('round-trips %s/%s/%s', (channel, botId, native) => {
+    const encoded = encodePlatformId(channel, botId, native);
+    expect(decodePlatformIdAs(encoded, 'v2')).toEqual({ channel, botId, native });
+  });
+});
+
+describe('namespacedPlatformId — backward-compat shim', () => {
+  // Existing helper retained as-is so callers that don't know a botId yet
+  // (CLI admin transport, native adapters that don't need v2) keep working.
+  it('prefixes raw chat ids that lack the channel tag', () => {
+    expect(namespacedPlatformId('telegram', '1190596288')).toBe('telegram:1190596288');
+  });
+
+  it('leaves already-prefixed ids alone', () => {
+    expect(namespacedPlatformId('telegram', 'telegram:foo')).toBe('telegram:foo');
+  });
+
+  it('leaves @-bearing ids (WhatsApp JIDs, iMessage) alone', () => {
+    expect(namespacedPlatformId('imessage', 'a@example.com')).toBe('a@example.com');
+  });
+
+  it('leaves +phone and group: ids (Signal) alone', () => {
+    expect(namespacedPlatformId('signal', '+15551234567')).toBe('+15551234567');
+    expect(namespacedPlatformId('signal', 'group:abc')).toBe('group:abc');
+  });
+});