agy-plugin-porter 0.0.0-stage → 0.2.0

package/lib/mod-lexer.mjs

@@ -0,0 +1,143 @@
+// A small JS/TS lexer for the mod scanner. It doesn't parse: it blanks comments and
+// the insides of strings, template text and regex literals, so structure (on(...),
+// $.noun.method, brackets) can be matched with plain regexes on the result, and
+// literal values read back from the source at the same offsets.
+// A `/` after one of these starts a regex. `<` is left out so JSX's `</Tag>` stays code.
+const REGEX_BEFORE = /[(,=:[!&|?{};+\-*%~^]$|(?:^|[^\w$])(?:return|typeof|case|do|else|in|of|void|yield|await)$/;
+
+export function blank(src) {
+  const out = src.split('');
+  const fill = (from, to) => { for (let k = from; k < to; k++) if (out[k] !== '\n') out[k] = ' '; };
+  const templates = []; // brace depth at each open `${`
+  let depth = 0;
+  let i = 0;
+  const skipString = (q) => {
+    const start = i++;
+    while (i < src.length && src[i] !== q && src[i] !== '\n') i += src[i] === '\\' ? 2 : 1;
+    fill(start + 1, i);
+    i++;
+  };
+  // Template text from i (just past ` or }) to the closing ` or the next ${.
+  const skipTemplate = () => {
+    const start = i;
+    while (i < src.length && src[i] !== '`' && !(src[i] === '$' && src[i + 1] === '{')) i += src[i] === '\\' ? 2 : 1;
+    fill(start, i);
+    if (src[i] === '`') { i++; return; }
+    templates.push(depth);
+    depth++;
+    i += 2;
+  };
+  while (i < src.length) {
+    const c = src[i];
+    if (c === '/' && src[i + 1] === '/') {
+      const end = src.indexOf('\n', i);
+      fill(i, end < 0 ? src.length : end);
+      i = end < 0 ? src.length : end;
+    } else if (c === '/' && src[i + 1] === '*') {
+      const end = src.indexOf('*/', i + 2);
+      fill(i, end < 0 ? src.length : end + 2);
+      i = end < 0 ? src.length : end + 2;
+    } else if (c === '"' || c === "'") {
+      skipString(c);
+    } else if (c === '`') {
+      i++;
+      skipTemplate();
+    } else if (c === '/' && REGEX_BEFORE.test(out.slice(Math.max(0, i - 12), i).join('').trimEnd() || ';')) {
+      const start = i++;
+      let inClass = false;
+      while (i < src.length && src[i] !== '\n' && (inClass || src[i] !== '/')) {
+        if (src[i] === '\\') i++;
+        else if (src[i] === '[') inClass = true;
+        else if (src[i] === ']') inClass = false;
+        i++;
+      }
+      fill(start + 1, i);
+      i++;
+    } else {
+      if (c === '{') depth++;
+      else if (c === '}') {
+        depth--;
+        if (templates.length && templates.at(-1) === depth) {
+          templates.pop();
+          i++;
+          skipTemplate();
+          continue;
+        }
+      }
+      i++;
+    }
+  }
+  return out.join('');
+}
+
+const PAIRS = { '(': ')', '[': ']', '{': '}' };
+
+// Index of the bracket that closes the one at `open` in blanked code, or -1.
+export function closeOf(code, open) {
+  const stack = [];
+  for (let i = open; i < code.length; i++) {
+    const c = code[i];
+    if (PAIRS[c]) stack.push(PAIRS[c]);
+    else if (c === ')' || c === ']' || c === '}') {
+      if (stack.pop() !== c) return -1;
+      if (!stack.length) return i;
+    }
+  }
+  return -1;
+}
+
+// The string literal whose opening quote is at `at` in code: {value, end} or null.
+// Template literals count only without ${...} parts.
+export function literalAt(code, src, at) {
+  const q = code[at];
+  if (q !== '"' && q !== "'" && q !== '`') return null;
+  const end = code.indexOf(q, at + 1);
+  if (end < 0) return null;
+  const body = src.slice(at + 1, end);
+  if (q === '`' && body.includes('${')) return null;
+  const value = body.replace(/\\(u\{[0-9a-fA-F]+\}|u[0-9a-fA-F]{4}|x[0-9a-fA-F]{2}|[\s\S])/g, (_, e) => {
+    if (e[0] === 'u' || e[0] === 'x') return String.fromCodePoint(Number.parseInt(e.replace(/[ux{}]/g, ''), 16));
+    return { n: '\n', t: '\t', r: '\r', b: '\b', f: '\f', v: '\v', 0: '\0', '\n': '' }[e] ?? e;
+  });
+  return { value, end };
+}
+
+// Top-level fields of the object literal at `open` (a `{` in code). Each value is
+// {literal}, {ident} or {other}.
+export function objectFields(code, src, open) {
+  const close = closeOf(code, open);
+  const fields = {};
+  if (close < 0) return fields;
+  let i = open + 1;
+  while (i < close) {
+    const key = /^\s*(?:([A-Za-z_$][\w$]*)|(["']))\s*/.exec(code.slice(i, close));
+    if (!key) break;
+    let name = key[1];
+    let j = i + key[0].length;
+    if (!name) {
+      const lit = literalAt(code, src, i + key[0].indexOf(key[2]));
+      if (!lit) break;
+      name = lit.value;
+      j = lit.end + 1;
+      j += /^\s*/.exec(code.slice(j))[0].length;
+    }
+    let end = j;
+    if (code[j] === ':') {
+      end = j + 1 + /^\s*/.exec(code.slice(j + 1))[0].length;
+      const lit = literalAt(code, src, end);
+      const ident = /^[A-Za-z_$][\w$]*/.exec(code.slice(end));
+      const after = (k) => /^\s*(?:as\s+const\s*)?[,}]/.test(code.slice(k, close + 1));
+      if (lit && after(lit.end + 1)) fields[name] = { literal: lit.value };
+      else if (ident && after(end + ident[0].length)) fields[name] = { ident: ident[0] };
+      else fields[name] = { other: true };
+    } else {
+      fields[name] = { ident: name }; // shorthand { name }
+    }
+    // Skip to the next top-level comma.
+    for (let k = end; k <= close; k++) {
+      if (PAIRS[code[k]]) { k = closeOf(code, k); if (k < 0) return fields; continue; }
+      if (code[k] === ',' || k === close) { i = k + 1; break; }
+    }
+  }
+  return fields;
+}

package/lib/mod-scan.mjs

@@ -0,0 +1,169 @@
+// Static scan of a Claude Code UI mod. Claude Code reads `on(...)` and
+// `$.noun.method(...)` literally from a mod's source (blast-radius's header), so the
+// porter can list a mod's events, host calls, commands, tools and render sites
+// without running it, then judge how well it ports (plan §5.5, §5.6).
+import { blank, closeOf, literalAt, objectFields } from './mod-lexer.mjs';
+
+// Antigravity's side of each Claude event (plan §5.4, scorecard in ui-mods-baseline.md).
+const EVENTS = {
+  'session.start': null,
+  'turn.start': null,
+  'turn.complete': null,
+  'tool.call': null,
+  'ui.render': null,
+  'command.run': ['partial', 'a generated skill calls its slash_<name> tool (one model turn), plus a button in the pane'],
+  'tool.describe': ['partial', 'applied once at tools/list; isDeferred has no equivalent'],
+  'prompt.context': ['partial', 'added once per turn as a systemMessage step, which shows in the transcript'],
+  'ui.close': ['partial', "only the pane's own × reports a close; closing Antigravity's pane tab sends nothing"],
+  'prompt.submit': ['none', 'agy has no user-prompt event'],
+  'prompt.compose': ['none', 'agy has no user-prompt event'],
+};
+const WORKS = new Set(['ui.resolve', 'ui.invalidate', 'ui.close', 'ui.toast', 'ui.status', 'ui.copy', 'store.keys', 'store.get',
+  'store.set', 'store.delete', 'state.get', 'state.set', 'clock.now', 'fs.read', 'session.cwd', 'session.id',
+  'command.register', 'tool.register', 'plugin.name']);
+const PARTIAL = {
+  'ui.open': 'only the person can show the pane, through a sidecar:// link or its tab',
+  'ui.panes': 'isPlaced and isShown count only views the person can see',
+  'prompt.fill': 'copies the text and asks the person to paste it; it never drafts or sends',
+};
+const NO_OPS = new Set(['ui.blit', 'ui.selection', 'session.messages']);
+const NO_OP_NOUNS = new Set(['model', 'agent']);
+const TIER3 = [/^process\.run$/, /^fs\.write$/, /^http\./, /^prompt\./];
+// Every ported pane mod gets these; they don't make a port partial (scorecard: task-board is clean).
+const FALLBACKS = new Set(['event command.run', '$.ui.open']);
+const SITES = { Pane: null, AbovePrompt: 'drawn as a strip above the pane', PromptHint: 'drawn as a strip above the pane' };
+
+export const isTranscriptSite = (component) => component !== '*' && !Object.hasOwn(SITES, component);
+
+function constants(code, src) {
+  const out = {};
+  for (const m of code.matchAll(/\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?=['"`])/g)) {
+    const lit = literalAt(code, src, m.index + m[0].length);
+    if (lit && /^\s*(?:as\s+const\s*)?(?:;|\n|$)/.test(code.slice(lit.end + 1))) out[m[1]] = lit.value;
+  }
+  return out;
+}
+
+const valueOf = (field, consts) => (field?.literal !== undefined ? field.literal : field?.ident && Object.hasOwn(consts, field.ident) ? consts[field.ident] : undefined);
+
+// Specifiers a file imports at runtime (type-only imports are erased by the transform).
+export function importsOf(src) {
+  const code = blank(src);
+  const out = [];
+  const at = (i) => literalAt(code, src, i)?.value;
+  // The clause between the keyword and the next quote is checked with plain string
+  // tests, not one backtracking regex: `import x from 'y'`, `import 'y'`, `export * from 'y'`.
+  for (const m of code.matchAll(/\b(import|export)\b/g)) {
+    const start = m.index + m[0].length;
+    const quote = [code.indexOf("'", start), code.indexOf('"', start)].filter((i) => i >= 0);
+    if (!quote.length) continue;
+    const q = Math.min(...quote);
+    const clause = code.slice(start, q);
+    if (!/^[\w$*{}\s,]*$/.test(clause)) continue;
+    const from = /\bfrom\s*$/.test(clause);
+    if (m[1] === 'export' ? !from : !from && clause.trim() !== '') continue;
+    if (/^\s+type\s/.test(clause)) continue; // type-only
+    const spec = at(q);
+    if (spec !== undefined) out.push(spec);
+  }
+  for (const m of code.matchAll(/(?<![\w$.])(?:import|require)\s*\(\s*(?=['"`])/g)) {
+    const spec = at(m.index + m[0].length);
+    if (spec !== undefined) out.push(spec);
+  }
+  return out;
+}
+
+// files: [{path, src}], the mod's module and the helpers it imports.
+export function scanMod(files) {
+  const scan = { events: [], calls: new Set(), commands: [], tools: [], renderSites: new Set(), imports: [], warnings: [], steersBuiltinTools: false };
+  for (const { path, src } of files) {
+    const code = blank(src);
+    const consts = constants(code, src);
+    for (const spec of importsOf(src)) scan.imports.push({ file: path, spec });
+
+    for (const m of code.matchAll(/(?<![\w$.])on\(\s*(?=['"])/g)) {
+      const lit = literalAt(code, src, m.index + m[0].length);
+      if (!lit) continue;
+      const paren = code.lastIndexOf('(', m.index + m[0].length);
+      const close = closeOf(code, paren);
+      const rest = /^\s*,\s*/.exec(code.slice(lit.end + 1));
+      const matcher = {};
+      if (rest && code[lit.end + 1 + rest[0].length] === '{') {
+        for (const [k, f] of Object.entries(objectFields(code, src, lit.end + 1 + rest[0].length))) {
+          const v = valueOf(f, consts);
+          matcher[k] = v ?? null;
+          if (v === undefined) scan.warnings.push(`${path}: on('${lit.value}') matcher "${k}" isn't a literal`);
+        }
+      }
+      const body = close > 0 ? code.slice(lit.end, close) : '';
+      scan.events.push({ event: lit.value, matcher, file: path });
+      if (lit.value === 'ui.render') scan.renderSites.add(matcher.component ?? '*');
+      const builtin = lit.value === 'tool.call' && !String(matcher.tool ?? '').startsWith('mcp__');
+      if (builtin && /\bdeny\s*:|\bnext\(\s*\{/.test(body)) scan.steersBuiltinTools = true;
+    }
+
+    for (const m of code.matchAll(/(?<![\w$.])\$\s*\.\s*([A-Za-z_$][\w$]*)(?:\s*\.\s*([A-Za-z_$][\w$]*))?/g)) {
+      if (m[2]) scan.calls.add(`${m[1]}.${m[2]}`);
+      else scan.warnings.push(`${path}: $.${m[1]} is used without a method, so its calls can't be scanned and will throw`);
+    }
+    if (/(?<![\w$.])\$\s*\[/.test(code) || /\}\s*=\s*\$(?![\w$.])/.test(code)) {
+      scan.warnings.push(`${path}: $ is accessed dynamically; calls the scan can't see will throw`);
+    }
+
+    for (const [kind, list] of [['command', scan.commands], ['tool', scan.tools]]) {
+      for (const m of code.matchAll(new RegExp(`(?<![\\w$.])\\$\\.${kind}\\.register\\(\\s*`, 'g'))) {
+        const at = m.index + m[0].length;
+        if (code[at] !== '{') { scan.warnings.push(`${path}: a $.${kind}.register argument isn't an object literal`); continue; }
+        const f = objectFields(code, src, at);
+        const def = { name: valueOf(f.name, consts), description: valueOf(f.description, consts), argumentHint: valueOf(f.argumentHint, consts) };
+        if (typeof def.name !== 'string') { scan.warnings.push(`${path}: a $.${kind}.register name isn't a literal`); continue; }
+        if (kind === 'tool') delete def.argumentHint;
+        if (!list.some((d) => d.name === def.name)) list.push(Object.fromEntries(Object.entries(def).filter(([, v]) => typeof v === 'string')));
+      }
+    }
+  }
+  // The runtime's 'claude-code' stand-in keeps atoms in $.state.
+  if (scan.imports.some((i) => i.spec === 'claude-code')) { scan.calls.add('state.get'); scan.calls.add('state.set'); }
+  scan.warnings = [...new Set(scan.warnings)];
+  return scan;
+}
+
+// Verdict, per-item findings and tier for a scan. `findings` are {item, level, reason}:
+// 'fallback' (every pane mod gets it, and the scorecard still calls the mod clean),
+// 'partial' or 'none'.
+export function assess(scan) {
+  const findings = [];
+  const refusals = [];
+  const add = (item, level, reason) => { if (FALLBACKS.has(item)) level = 'fallback'; if (!findings.some((f) => f.item === item)) findings.push({ item, level, reason }); };
+  for (const { event } of scan.events) {
+    const known = Object.hasOwn(EVENTS, event) ? EVENTS[event] : ['none', 'no Antigravity equivalent; the handler never runs'];
+    if (known) add(`event ${event}`, ...known);
+  }
+  for (const call of scan.calls) {
+    const [noun] = call.split('.');
+    if (WORKS.has(call)) continue;
+    if (Object.hasOwn(PARTIAL, call)) add(`$.${call}`, 'partial', PARTIAL[call]);
+    else if (NO_OPS.has(call) || NO_OP_NOUNS.has(noun)) add(`$.${call}`, 'partial', 'returns nothing in the Antigravity port');
+    else add(`$.${call}`, 'none', 'not available in the Antigravity port (calls reject)');
+  }
+  const sites = [...scan.renderSites];
+  for (const site of sites) {
+    if (isTranscriptSite(site)) add(`render ${site}`, 'none', 'transcript render sites have no Antigravity equivalent');
+    else if (SITES[site]) add(`render ${site}`, 'partial', SITES[site]);
+  }
+  if (sites.length && sites.every(isTranscriptSite)) {
+    refusals.push(`draws only into transcript sites (${sites.join(', ')}), which Antigravity has no equivalent for`);
+  }
+  const bare = [...new Set(scan.imports.filter((i) => !/^\.{1,2}\//.test(i.spec) && i.spec !== 'claude-code').map((i) => i.spec))];
+  if (bare.length) refusals.push(`imports ${bare.join(', ')}, which a ported mod can't load (only relative files and 'claude-code')`);
+  const hasPane = scan.renderSites.has('Pane') || scan.renderSites.has('*');
+  const warnings = [...scan.warnings];
+  if (!hasPane && sites.some((s) => SITES[s])) warnings.push('no Pane: AbovePrompt/PromptHint draw only while the pane is open');
+
+  const tierReasons = ['a sidecar is a full Node process outside agy\'s permission prompts'];
+  for (const call of scan.calls) if (TIER3.some((re) => re.test(call))) tierReasons.push(`$.${call}`);
+  if (scan.steersBuiltinTools) tierReasons.push('tool.call can deny or rewrite built-in tool calls');
+  const tier = tierReasons.length > 1 ? 'TIER_3_AGENT_CONTROL' : 'TIER_2_LOCAL_TOOLING';
+  const verdict = refusals.length ? 'refused' : findings.some((f) => f.level !== 'fallback') ? 'partial' : 'clean';
+  return { verdict, refusals, findings, warnings, hasPane, tier, tierReasons };
+}

package/lib/mod-transform.mjs

@@ -0,0 +1,84 @@
+// Collects a UI mod's module graph and turns it into files a sidecar can import.
+// TS/TSX/JSX go through esbuild, an optional dependency of the porter loaded only for
+// them (plan §5.8, picked by the 2.5A scorecard). Plain .js/.mjs mods need nothing.
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { extname, join, posix, relative } from 'node:path';
+
+import { importsOf } from './mod-scan.mjs';
+
+export const NEEDS_TRANSFORM = new Set(['.ts', '.tsx', '.jsx', '.mts']);
+const TRY_EXT = ['', '.ts', '.tsx', '.js', '.mjs', '.jsx', '/index.ts', '/index.tsx', '/index.js', '/index.mjs'];
+
+// esbuild, or null when it isn't installed.
+export function loadEsbuild() {
+  try { return createRequire(import.meta.url)('esbuild'); } catch { return null; }
+}
+
+const isFile = (p) => existsSync(p) && statSync(p).isFile();
+
+// Resolves a relative specifier from `fromRel` (posix, relative to root). A `.js`
+// specifier may name a `.ts` file (TypeScript's convention). Type declarations
+// (.d.ts) resolve to null: imports of them are erased by the transform.
+export function resolveSpec(root, fromRel, spec) {
+  const base = posix.normalize(posix.join(posix.dirname(fromRel), spec));
+  if (base.startsWith('../') || base === '..') throw new Error(`${fromRel} imports ${spec}, outside the plugin`);
+  const stem = /\.(m?js|jsx)$/.test(base) ? base.replace(/\.(m?js|jsx)$/, '') : null;
+  for (const cand of [...TRY_EXT.map((e) => base + e), ...(stem ? ['.ts', '.tsx', '.mts'].map((e) => stem + e) : [])]) {
+    if (cand.endsWith('.d.ts')) continue;
+    if (isFile(join(root, cand))) return cand;
+  }
+  for (const e of ['.d.ts', '/index.d.ts']) if (isFile(join(root, base + e))) return null;
+  throw new Error(`${fromRel} imports ${spec}, which isn't in the plugin`);
+}
+
+// The module and every relative file it imports at runtime: [{rel, src}].
+export function collectGraph(root, entryRel) {
+  const files = new Map();
+  const queue = [entryRel];
+  while (queue.length) {
+    const rel = queue.shift();
+    if (files.has(rel)) continue;
+    const src = readFileSync(join(root, rel), 'utf8').replace(/^\uFEFF/, '');
+    files.set(rel, src);
+    for (const spec of importsOf(src)) {
+      if (!/^\.{1,2}\//.test(spec)) continue;
+      const target = resolveSpec(root, rel, spec);
+      if (target) queue.push(target);
+    }
+  }
+  return [...files].map(([rel, src]) => ({ rel, src }));
+}
+
+// Output name inside the sidecar's mod/ folder: always .mjs, so Node loads every file
+// as ESM whatever its version.
+export const outName = (rel) => rel.replace(/\.(tsx?|mts|jsx|m?js)$/, '') + '.mjs';
+
+export const needsTransform = (files) => files.some((f) => NEEDS_TRANSFORM.has(extname(f.rel)));
+
+// Transforms one file and points its imports at the output names: relative files at
+// their .mjs copies, 'claude-code' at the runtime's stand-in next to mod/.
+export function transformFile(root, file, esbuild) {
+  const ext = extname(file.rel);
+  let code = file.src;
+  if (NEEDS_TRANSFORM.has(ext)) {
+    if (!esbuild) throw new Error('needs esbuild to transform TS/TSX: port it with `npx agy-plugin-porter`, which installs esbuild as an optional dependency');
+    code = esbuild.transformSync(file.src, {
+      loader: ext === '.mts' ? 'ts' : ext.slice(1), format: 'esm', jsx: 'transform', jsxFactory: 'h', jsxFragment: 'Fragment',
+      target: 'node20', sourcefile: file.rel,
+    }).code;
+  }
+  const outDir = posix.dirname(`mod/${outName(file.rel)}`);
+  const stand = posix.relative(outDir, 'claude-code.mjs');
+  const rewrite = (spec) => {
+    if (spec === 'claude-code') return stand.startsWith('.') ? stand : `./${stand}`;
+    if (!/^\.{1,2}\//.test(spec)) return spec;
+    const target = resolveSpec(root, file.rel, spec);
+    if (!target) return spec;
+    const r = posix.relative(posix.dirname(file.rel), outName(target));
+    return r.startsWith('.') ? r : `./${r}`;
+  };
+  return code.replace(/(\bfrom\s*|\bimport\s*\(\s*|\bimport\s+)(['"])([^'"\n]+)\2/g, (whole, lead, q, spec) => `${lead}${q}${rewrite(spec)}${q}`);
+}
+
+export const relPosix = (from, to) => relative(from, to).split('\\').join('/');

package/lib/mode-compiler.mjs

@@ -0,0 +1,195 @@
+// Turns Claude Code agents and Roo/Kilo modes into agy agents (agents/<name>.md).
+// agy 1.4.x skips a Claude agent outright: `tools: Read, Grep` is a string
+// where agy wants a list, and `model: sonnet` isn't an agy model tier. So
+// tools are mapped to agy tool names, and models to agy's tiers (pro, flash,
+// flash_lite, inherit). Anything that can't be mapped is reported.
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+import { rewriteRuleVars } from './rules-compiler.mjs';
+import { slugifyName } from './skill-compiler.mjs';
+import { ROO_GROUPS, TOOLS, unmappedToolReason } from './tool-map.mjs';
+import { formatFrontmatter, parseYaml, splitFrontmatter } from './yaml-lite.mjs';
+
+// Names agy reserves for built-in agents (seen in agy 1.4.5's subagent list).
+const RESERVED = new Set(['self', 'research', 'image-generator']);
+const CLAUDE_AGENT_KEYS = new Set(['name', 'description', 'tools', 'model']);
+
+export function mapClaudeModel(model) {
+  if (model === undefined || model === null || model === '') return { tier: undefined };
+  const m = String(model).toLowerCase();
+  if (m === 'inherit') return { tier: 'inherit' };
+  if (m.includes('haiku')) return { tier: 'flash' };
+  if (m.includes('opus') || m.includes('sonnet')) return { tier: 'pro' };
+  return { tier: undefined, dropped: true };
+}
+
+// Splits `Read, Bash(git diff:*), Agent(a, b)` on top-level commas only.
+export function splitToolList(text) {
+  const parts = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === '(') depth++;
+    else if (text[i] === ')') depth = Math.max(0, depth - 1);
+    else if (text[i] === ',' && depth === 0) { parts.push(text.slice(start, i)); start = i + 1; }
+  }
+  parts.push(text.slice(start));
+  return parts;
+}
+
+export function mapClaudeTools(tools) {
+  const list = Array.isArray(tools) ? tools : splitToolList(String(tools));
+  const mapped = new Set();
+  const unmapped = [];
+  let mcp = false;
+  for (const raw of list.map((t) => String(t).trim()).filter(Boolean)) {
+    // `Bash(git diff:*)` -> `Bash`, without a regex that backtracks over "(".
+    const paren = raw.indexOf('(');
+    const name = (paren > 0 && raw.endsWith(')') ? raw.slice(0, paren) : raw).trim();
+    if (name.startsWith('mcp__')) mcp = true;
+    else if (TOOLS.claude[name]) TOOLS.claude[name].forEach((t) => mapped.add(t));
+    else unmapped.push(name);
+  }
+  return { tools: [...mapped].sort(), unmapped, mcp };
+}
+
+function agentName(raw, slug, report, item) {
+  let name = slugifyName(raw);
+  if (RESERVED.has(name)) {
+    report.warnings.push(`${item}: "${name}" is a built-in agy agent name; renamed to "${slug}-${name}"`);
+    name = `${slug}-${name}`;
+  }
+  return name;
+}
+
+function compileClaudeAgents(pluginDir, { slug, report, taken }) {
+  const dir = join(pluginDir, 'agents');
+  if (!existsSync(dir)) return;
+  for (const file of readdirSync(dir).filter((f) => f.endsWith('.md'))) {
+    const item = `agent:${basename(file, '.md')}`;
+    let parsed;
+    try { parsed = splitFrontmatter(readFileSync(join(dir, file), 'utf8')); } catch (err) {
+      report.unported.push({ item, reason: `frontmatter isn't parseable: ${err.message}` });
+      rmSync(join(dir, file));
+      continue;
+    }
+    const { data, body } = parsed;
+    const name = agentName(data.name ?? basename(file, '.md'), slug, report, item);
+    const rawDesc = typeof data.description === 'string' && data.description.trim() ? data.description : `Ported agent ${name}.`;
+    const out = { name, description: rewriteRuleVars(rawDesc, item, report) };
+    if (data.tools !== undefined && data.tools !== null && data.tools !== '*') {
+      const mapped = mapClaudeTools(data.tools);
+      out.tools = mapped.tools;
+      for (const t of mapped.unmapped) report.unported.push({ item: `${item} tool ${t}`, reason: unmappedToolReason(t) });
+      if (mapped.mcp) {
+        out.inheritMcp = true;
+        report.warnings.push(`${item}: MCP tools in "tools" became inheritMcp: true (all MCP tools, not just the listed ones)`);
+      }
+    }
+    const model = mapClaudeModel(data.model);
+    if (model.tier) out.model = model.tier;
+    if (model.dropped) report.warnings.push(`${item}: model "${data.model}" has no agy tier; the agent inherits the session's model`);
+    out.subagent = true;
+    const extra = Object.keys(data).filter((k) => !CLAUDE_AGENT_KEYS.has(k));
+    if (extra.length) report.warnings.push(`${item}: dropped ${extra.join(', ')}`);
+    rmSync(join(dir, file));
+    const cleanBody = rewriteRuleVars(body, item, report);
+    writeFileSync(join(dir, `${name}.md`), formatFrontmatter(out, cleanBody));
+    taken.add(name);
+    report.ported.push(`${item} → agents/${name}.md`);
+  }
+}
+
+function readModes(srcDir, report) {
+  const modes = [];
+  for (const file of ['.roomodes', '.kilocodemodes']) {
+    const path = join(srcDir, file);
+    if (!existsSync(path)) continue;
+    const text = readFileSync(path, 'utf8').replace(/^/, '');
+    let parsed;
+    try { parsed = text.trim().startsWith('{') ? JSON.parse(text) : parseYaml(text); } catch (err) {
+      report.unported.push({ item: file, reason: `can't parse: ${err.message}` });
+      continue;
+    }
+    for (const mode of parsed?.customModes ?? []) modes.push({ ...mode, file });
+  }
+  return modes;
+}
+
+function modeRules(srcDir, slug) {
+  const texts = [];
+  for (const dir of [`.roo/rules-${slug}`, `.kilocode/rules-${slug}`]) {
+    const full = join(srcDir, dir);
+    if (!existsSync(full)) continue;
+    for (const f of readdirSync(full).filter((x) => /\.(md|txt)$/i.test(x)).sort()) texts.push(readFileSync(join(full, f), 'utf8').trim());
+  }
+  for (const f of [`.roorules-${slug}`, `.clinerules-${slug}`]) {
+    if (existsSync(join(srcDir, f))) texts.push(readFileSync(join(srcDir, f), 'utf8').trim());
+  }
+  return texts.filter(Boolean);
+}
+
+// Restricted edit groups (`fileRegex`) aren't granted: agy agents can't limit
+// edits to a pattern, and widening a mode's permissions silently is worse than
+// reporting the gap.
+export function mapRooGroups(groups, item, report) {
+  const tools = new Set();
+  let mcp = false;
+  for (const group of Array.isArray(groups) ? groups : []) {
+    const [kind, options] = Array.isArray(group) ? group : [group, null];
+    if (kind === 'mcp') { mcp = true; continue; }
+    if (!ROO_GROUPS[kind]) {
+      report.unported.push({ item: `${item} group ${kind}`, reason: kind === 'browser' ? "agy's browser tool names aren't mapped yet" : 'unknown tool group' });
+      continue;
+    }
+    if (options?.fileRegex) {
+      report.unported.push({ item: `${item} group ${kind} (${options.fileRegex})`, reason: "agy agents can't restrict edits to a file pattern, so the group isn't granted" });
+      continue;
+    }
+    ROO_GROUPS[kind].forEach((t) => tools.add(t));
+  }
+  return { tools: [...tools].sort(), mcp };
+}
+
+function compileRooModes(pluginDir, { srcDir, slug, report, taken }) {
+  const modes = readModes(srcDir, report);
+  if (!modes.length) return;
+  const dir = join(pluginDir, 'agents');
+  mkdirSync(dir, { recursive: true });
+  for (const mode of modes) {
+    const item = `mode:${mode.slug ?? '?'}`;
+    if (typeof mode.slug !== 'string' || typeof mode.roleDefinition !== 'string') {
+      report.unported.push({ item, reason: 'a mode needs slug and roleDefinition' });
+      continue;
+    }
+    const name = agentName(mode.slug, slug, report, item);
+    if (taken.has(name)) {
+      report.unported.push({ item, reason: `an agent named ${name} already exists in the plugin` });
+      continue;
+    }
+    const { tools, mcp } = mapRooGroups(mode.groups, item, report);
+    const rawDesc = mode.whenToUse || mode.description || mode.roleDefinition.split(/(?<=\.)\s/)[0];
+    const description = rewriteRuleVars(rawDesc, item, report);
+    const out = { name, description, tools, ...(mcp ? { inheritMcp: true } : {}), mainAgent: true, subagent: true };
+    const rawBody = [`# ${mode.name ?? mode.slug}`, mode.roleDefinition.trim(), mode.customInstructions?.trim(), ...modeRules(srcDir, mode.slug)]
+      .filter(Boolean).join('\n\n');
+    const body = rewriteRuleVars(rawBody, item, report);
+    writeFileSync(join(dir, `${name}.md`), formatFrontmatter(out, `\n${body}\n`));
+    taken.add(name);
+    report.ported.push(`${item} → agents/${name}.md`);
+    for (const f of [`.roo/system-prompt-${mode.slug}`, `.kilocode/system-prompt-${mode.slug}`]) {
+      if (existsSync(join(srcDir, f))) {
+        report.unported.push({ item: `${item} ${f}`, reason: "it replaces the whole system prompt, which an agy agent can't do; the agent has only the mode's role definition and instructions" });
+      }
+    }
+  }
+}
+
+export function compileModes(pluginDir, { srcDir, ecosystems, slug }) {
+  const report = { ported: [], unported: [], warnings: [] };
+  const taken = new Set();
+  if (ecosystems.includes('claude')) compileClaudeAgents(pluginDir, { slug, report, taken });
+  if (ecosystems.includes('roo')) compileRooModes(pluginDir, { srcDir, slug, report, taken });
+  return report;
+}