@kyun.si/agent2cursor 0.0.0-stage → 0.1.1

package/dist/emit/common.d.ts

@@ -0,0 +1,4 @@
+export declare function literal(value: unknown): string;
+export declare function todo(message: string): string;
+export declare function assertId(id: string, kind: string): void;
+export declare function markdown(value: string): string;

package/dist/emit/common.js

@@ -0,0 +1,15 @@
+export function literal(value) {
+    return JSON.stringify(value).replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029");
+}
+export function todo(message) {
+    return message.split(/[\r\n\u2028\u2029]+/u).map((line) => `  // TODO(agent2cursor): ${line}`).join("\n");
+}
+export function assertId(id, kind) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/u.test(id)) {
+        throw new Error(`Invalid ${kind} id: ${JSON.stringify(id)}`);
+    }
+}
+export function markdown(value) {
+    return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")
+        .replaceAll("|", "\\|").replaceAll("`", "&#96;").replace(/[\r\n]+/gu, " ");
+}

package/dist/emit/evals.d.ts

@@ -0,0 +1,4 @@
+import type { ConvertOptions, MigrationIR } from "../ir.js";
+export declare function renderEvalConfig(): string;
+export declare function renderSkillEvals(ir: MigrationIR, options: ConvertOptions): string;
+export declare function renderSubagentEvals(ir: MigrationIR, options: ConvertOptions): string;

package/dist/emit/evals.js

@@ -0,0 +1,33 @@
+import { literal } from "./common.js";
+const ROUTING_TIMEOUT_MS = 240_000;
+export function renderEvalConfig() {
+    return 'import { defineEvalConfig } from "@grok/agent-sdk/evals";\n\nexport default defineEvalConfig({ maxConcurrency: 2 });\n';
+}
+export function renderSkillEvals(ir, options) {
+    const cases = ir.skills.map((skill) => {
+        const trigger = skill.trigger || (options.lang === "zh" ? `请使用 ${skill.id} skill。` : `Use the ${skill.id} skill.`);
+        const scope = options.lang === "zh"
+            ? `\n先读取 ${skill.id} 的 SKILL.md，再按其中的格式做一个最小例子。不要执行其中的脚本，不要写文件，不要提交或合并 PR。`
+            : `\nRead ${skill.id}'s SKILL.md, then produce one minimal example in its format. Do not run its scripts, write files, commit, or merge a PR.`;
+        return [
+            "    {", `      id: ${literal(skill.id)},`,
+            "      async test(t) {", `        await t.send(${literal(trigger + scope)});`,
+            "        t.succeeded();", `        t.loadedSkill(${literal(skill.id)});`,
+            "      },", "    },",
+        ].join("\n");
+    });
+    return ['import { defineEval } from "@grok/agent-sdk/evals";', "", "export default defineEval({", '  tags: ["migration", "routing"],', `  timeoutMs: ${ROUTING_TIMEOUT_MS},`, "  cases: [", ...cases, "  ],", "});", ""].join("\n");
+}
+export function renderSubagentEvals(ir, options) {
+    const cases = ir.agents.map((agent) => {
+        const prompt = options.lang === "zh"
+            ? `请通过 task 把一件符合 ${agent.id} 职责的最小例子交给 ${agent.id} 子代理，不要由根代理代答。让它按自己的说明完成，并在最终回复里给出结论。`
+            : `Use task to delegate one minimal example matching the ${agent.id} subagent's role to ${agent.id}. The root agent must not answer on its behalf. Let the subagent follow its own instructions and put its conclusion in the final reply.`;
+        return [
+            "    {", `      id: ${literal(agent.id)},`, "      async test(t) {",
+            `        await t.send(${literal(prompt)});`, "        t.succeeded();",
+            `        t.calledSubagent(${literal(agent.id)});`, "      },", "    },",
+        ].join("\n");
+    });
+    return ['import { defineEval } from "@grok/agent-sdk/evals";', "", "export default defineEval({", '  tags: ["migration", "routing"],', `  timeoutMs: ${ROUTING_TIMEOUT_MS},`, "  cases: [", ...cases, "  ],", "});", ""].join("\n");
+}

package/dist/emit/project.d.ts

@@ -0,0 +1,2 @@
+import { type ConvertOptions, type MigrationIR, type ProjectPlan, type ValidationResult } from "../ir.js";
+export declare function planProject(source: MigrationIR, options: ConvertOptions, validation?: ValidationResult): Promise<ProjectPlan>;

package/dist/emit/project.js

@@ -0,0 +1,165 @@
+import { readFile } from "node:fs/promises";
+import { posix, relative, sep } from "node:path";
+import { stringify } from "yaml";
+import { SDK_VERSION } from "../ir.js";
+import { listSafeFiles, readSafeFile } from "../scan/safety.js";
+import { assertId, literal, markdown } from "./common.js";
+import { renderEvalConfig, renderSkillEvals, renderSubagentEvals } from "./evals.js";
+import { renderReport } from "./report.js";
+import { renderSubagent } from "./subagent.js";
+import { renderToolStub } from "./tool-stub.js";
+import { associatedTstackLicense } from "./tstack-license.js";
+const MAX_PROJECT_BYTES = 128 * 1024 * 1024;
+function packageName(name) {
+    return name.toLowerCase().replace(/[^a-z0-9-]+/gu, "-").replace(/^-+|-+$/gu, "").slice(0, 214) || "converted-agent";
+}
+function addFinding(ir, finding) {
+    if (!ir.findings.some((item) => item.source === finding.source && item.field === finding.field && item.message === finding.message))
+        ir.findings.push(finding);
+}
+function skillPreloadHints(ir, options) {
+    const agents = new Map();
+    const rootLines = [];
+    for (const agent of ir.agents) {
+        if (agent.sourceFormat === "codex")
+            continue;
+        const raw = agent.frontmatter.skills;
+        if (raw === undefined)
+            continue;
+        if (!Array.isArray(raw) || !raw.every((item) => typeof item === "string" && !!item.trim())) {
+            addFinding(ir, { source: agent.source, field: "[skills preload hint]", status: "degraded", message: "skills 不是有效的字符串数组，未生成加载提示。请检查原字段并手动配置共享 skill。", messageEn: "skills is not a valid array of names; no load hint was generated. Review the source field and configure shared skills manually." });
+            continue;
+        }
+        if (!raw.length)
+            continue;
+        const matches = raw.map((name) => ({ name, skill: ir.skills.find((skill) => skill.id === name || skill.frontmatter.name === name) }));
+        const available = matches.flatMap(({ skill }) => skill ? [skill.id] : []);
+        const missing = matches.filter(({ skill }) => !skill).map(({ name }) => name);
+        const list = available.map((id) => `\`${id}\``).join(", ");
+        const hint = options.lang === "zh"
+            ? `Claude 的 skills 预加载没有原生等价行为。${available.length ? `需要时请根代理先加载共享 skill：${list}，再委派给本子代理。` : "没有找到对应的已迁移共享 skill。"}${missing.length ? ` 尚未一并迁移：${missing.map(markdown).join(", ")}；请先补充这些 skill。` : ""} 这只是提示，不是自动预加载或权限隔离。`
+            : `Claude skill preloading has no native equivalent. ${available.length ? `When needed, ask the root agent to load shared skills ${list} before delegating to this subagent.` : "No corresponding migrated shared skill was found."}${missing.length ? ` Missing from this conversion: ${missing.map(markdown).join(", ")}; convert these skills first.` : ""} This is a hint, not automatic preloading or permission isolation.`;
+        agents.set(agent.id, `\n\n<!-- agent2cursor migration hint -->\n${hint}\n`);
+        rootLines.push(`- \`${agent.id}\`: ${hint}`);
+        addFinding(ir, { source: agent.source, field: "[skills preload hint]", status: "degraded", target: `bot/subagents/${agent.id}/instructions.md; bot/instructions.md`, message: `已添加共享 skill 加载提示；不是自动预加载。${missing.length ? " 部分引用 skill 未包含在本次输入中，请一并转换。" : ""}`, messageEn: `Added shared-skill load hints, not automatic preloading.${missing.length ? " Some referenced skills are absent; convert them as well." : ""}` });
+    }
+    return { root: rootLines.length ? `\n## ${options.lang === "zh" ? "子代理 skill 加载提示" : "Subagent skill loading hints"}\n\n${rootLines.join("\n")}\n` : "", agents };
+}
+export async function planProject(source, options, validation) {
+    // Planning is pure with respect to the input IR and output filesystem.
+    const ir = structuredClone(source);
+    const files = new Map();
+    const pathKeys = new Set();
+    let totalBytes = 0;
+    const add = (path, contents) => {
+        if (path.includes("\\") || posix.isAbsolute(path) || path.split("/").some((part) => part === ".." || part === "." || part === ""))
+            throw new Error(`Unsafe output path: ${JSON.stringify(path)}`);
+        // Refuse case-folded collisions too: generated projects must be portable to macOS/Windows.
+        const key = path.normalize("NFC").toLowerCase();
+        if (pathKeys.has(key))
+            throw new Error(`Output path collision: ${JSON.stringify(path)}`);
+        const bytes = typeof contents === "string" ? Buffer.byteLength(contents, "utf8") : contents.length;
+        if (totalBytes + bytes > MAX_PROJECT_BYTES)
+            throw new Error("Generated project exceeds the 128 MiB size limit. Split the conversion into smaller inputs.");
+        totalBytes += bytes;
+        pathKeys.add(key);
+        files.set(path, contents);
+    };
+    for (const [kind, assets] of [["subagent", ir.agents], ["skill", ir.skills], ["tool", ir.scripts]]) {
+        const seen = new Set();
+        for (const asset of assets) {
+            assertId(asset.id, kind);
+            const key = asset.id.toLowerCase();
+            if (seen.has(key))
+                throw new Error(`Duplicate ${kind} id: ${asset.id}`);
+            seen.add(key);
+        }
+    }
+    add("package.json", JSON.stringify({
+        name: packageName(options.name), version: "0.1.0", private: true, type: "module",
+        engines: { node: ">=22.13" },
+        scripts: { dev: "agent-sdk dev", validate: "agent-sdk validate --dir .", eval: "agent-sdk eval --dir ." },
+        dependencies: { "@grok/agent-sdk": SDK_VERSION, zod: "^3.25.0" },
+    }, null, 2) + "\n");
+    add(".gitignore", "node_modules/\n.env\n.env.*\n!.env.example\n.agent-sdk/\n.agent-serve/\n.cursor/\n");
+    add("bot/agent.ts", [
+        'import { defineAgent } from "@grok/agent-sdk";', "", "export default defineAgent({",
+        `  name: ${literal(options.name)},`, "  local: { sandbox: true },",
+        ...(options.rootTools === undefined ? [] : [`  tools: ${literal(options.rootTools)},`]),
+        "});", "",
+    ].join("\n"));
+    const template = await readFile(new URL(`../../templates/${options.lang}/instructions.md`, import.meta.url), "utf8");
+    const preloadHints = skillPreloadHints(ir, options);
+    const delegation = ir.agents.length
+        ? (options.lang === "zh" ? "\n## 可委派的子代理\n\n" : "\n## Available subagents\n\n") + ir.agents.map((agent) => `- \`${agent.id}\`: ${agent.description.replace(/[\r\n]+/gu, " ")}`).join("\n") + "\n"
+        : "";
+    add("bot/instructions.md", template.replaceAll("{{name}}", options.name) + delegation + preloadHints.root);
+    for (const agent of ir.agents) {
+        const hint = preloadHints.agents.get(agent.id) ?? "";
+        if (hint) {
+            const bodyFinding = { source: agent.source, field: "$body", status: "degraded", target: `bot/subagents/${agent.id}/instructions.md`,
+                message: "保留原文，正文末尾追加共享 skill 预加载提示（`<!-- agent2cursor migration hint -->`）；输出正文并非逐字不变。提示不实现自动预加载。",
+                messageEn: "Original text retained, with a shared-skill preload hint appended after `<!-- agent2cursor migration hint -->`; the output body is not byte-for-byte unchanged. The hint does not implement automatic preloading." };
+            // Replace both inventories so the report cannot retain a contradictory scan-time conclusion.
+            ir.findings = ir.findings.filter(f => !(f.source === agent.source && f.field === "$body"));
+            agent.findings = agent.findings.filter(f => f.field !== "$body");
+            ir.findings.push(bodyFinding);
+            agent.findings.push(bodyFinding);
+        }
+        add(`bot/subagents/${agent.id}/agent.ts`, renderSubagent(agent, options));
+        add(`bot/subagents/${agent.id}/instructions.md`, agent.body + hint);
+    }
+    const tstackSources = new Map();
+    for (const skill of ir.skills) {
+        const license = await associatedTstackLicense(skill);
+        if (license) {
+            const source = tstackSources.get(license.root) ?? { license, skills: [] };
+            source.skills.push(skill.id);
+            tstackSources.set(license.root, source);
+            addFinding(ir, { source: license.source, field: "[tstack license]", status: "mapped", target: "LICENSE-tstack; TSTACK-PROVENANCE.json", message: "已核对并保留 t3dotgg/tstack 的 Theo Browne MIT 版权与许可全文；不表示官方关联或背书。当前本地输入的 Git 版本未核实，见来源记录。", messageEn: "Verified and preserved the complete Theo Browne MIT copyright and license from t3dotgg/tstack; no affiliation or endorsement is implied. The input's Git revision is unverified; see provenance." });
+        }
+        const safeFiles = await listSafeFiles(skill.directory, (path, reason) => {
+            addFinding(ir, { source: path, field: "[excluded path]", status: "dropped", message: `辅助目录未复制：${reason}。如确有需要，请人工审核后添加。`, messageEn: `Supporting directory excluded: ${reason}. Review and add manually if required.` });
+        });
+        const frontmatter = { ...skill.frontmatter, name: skill.id, description: skill.description };
+        add(`bot/skills/${skill.id}/SKILL.md`, `---\n${stringify(frontmatter).trimEnd()}\n---\n${skill.body}`);
+        for (const file of safeFiles) {
+            const localPath = relative(skill.directory, file).split(sep).join("/");
+            if (localPath === "SKILL.md")
+                continue;
+            add(`bot/skills/${skill.id}/${localPath}`, await readSafeFile(file));
+            addFinding(ir, { source: file, field: "[supporting file]", status: "mapped", target: `bot/skills/${skill.id}/${localPath}`, message: "原样复制辅助文件；复制不表示自动执行或支持其运行时元数据。", messageEn: "Supporting file copied unchanged; copying does not execute it or imply support for its runtime metadata." });
+        }
+    }
+    if (tstackSources.size) {
+        const sources = [...tstackSources.values()];
+        add("LICENSE-tstack", sources[0].license.bytes);
+        add("TSTACK-PROVENANCE.json", JSON.stringify({
+            repository: "https://github.com/t3dotgg/tstack", license: "MIT", copyright: "Copyright (c) 2026 Theo Browne",
+            sourceRevision: "unverified", outputLicenseSha256: sources[0].license.sha256,
+            modifications: "Skill frontmatter normalized; source bodies and supporting files retained; disabled script stubs and routing evals generated. See the migration report.",
+            inputs: sources.map(({ license, skills }) => ({ directory: license.root, licenseSha256: license.sha256, skills })),
+        }, null, 2) + "\n");
+        add("THIRD_PARTY_NOTICES.md", options.lang === "zh"
+            ? "# 第三方声明\n\n本项目包含来自 [t3dotgg/tstack](https://github.com/t3dotgg/tstack) 的 skills，Copyright (c) 2026 Theo Browne，按 MIT 许可提供；许可全文见 [LICENSE-tstack](LICENSE-tstack)。与 Theo Browne / T3 无官方关联或背书关系。当前输入版本未核实；转换改动与本地来源见 TSTACK-PROVENANCE.json 及迁移报告。\n\n@grok/agent-sdk 仅作为依赖引用，使用受其许可证及 Cursor 服务条款约束。\n"
+            : "# Third-party notices\n\nThis project includes skills from [t3dotgg/tstack](https://github.com/t3dotgg/tstack), Copyright (c) 2026 Theo Browne, under the MIT license; the full notice is in [LICENSE-tstack](LICENSE-tstack). No official affiliation or endorsement by Theo Browne / T3 is implied. The input revision is unverified; see TSTACK-PROVENANCE.json and the migration report for local sources and conversion changes.\n\n@grok/agent-sdk is referenced only as a dependency and remains subject to its own license and Cursor terms.\n");
+    }
+    for (const script of ir.scripts) {
+        assertId(script.skillId, "skill");
+        if (!ir.skills.some((skill) => skill.id === script.skillId))
+            throw new Error(`Script ${script.id} references missing skill ${script.skillId}`);
+        add(`bot/tools/${script.id}.ts`, renderToolStub(script, options));
+        addFinding(ir, { source: script.source, field: "[script tool]", status: "degraded", target: `bot/tools/${script.id}.ts`, message: "已生成 execution: agent 的禁用存根，始终返回 TODO 错误。审核原脚本、补齐参数 schema 与 JSON stdin/stdout 协议后再启用；agent tool 需要 shell，且不支持 effect / dryRunResult / needsApproval。", messageEn: "Generated a disabled execution: agent stub that always returns a TODO error. Review the original script and implement a typed JSON stdin/stdout contract before enabling. Agent tools require shell and do not support effect / dryRunResult / needsApproval." });
+    }
+    if (options.rootTools && ir.agents.length && !options.rootTools.includes("task"))
+        addFinding(ir, { source: "bot/agent.ts", field: "tools", status: "degraded", message: "显式根工具白名单未包含 task，子代理不能被委派，生成的委派 eval 会失败。请按需要添加 task。", messageEn: "The explicit root allowlist omits task, so subagents cannot be delegated to and delegation evals will fail. Add task if needed." });
+    if (options.rootTools && ir.scripts.length && !options.rootTools.includes("shell"))
+        addFinding(ir, { source: "bot/agent.ts", field: "tools", status: "degraded", message: "显式根工具白名单未包含 shell，agent 脚本工具不能运行。实现并审核工具后，再决定是否添加 shell。", messageEn: "The explicit root allowlist omits shell, so agent script tools cannot run. Decide whether to add shell after implementing and reviewing them." });
+    add("evals/evals.config.ts", renderEvalConfig());
+    if (ir.skills.length)
+        add("evals/skills.eval.ts", renderSkillEvals(ir, options));
+    if (ir.agents.length)
+        add("evals/subagents.eval.ts", renderSubagentEvals(ir, options));
+    add(options.lang === "zh" ? "MIGRATION.zh-CN.md" : "MIGRATION.en.md", renderReport(ir, options, validation));
+    return { files, ir };
+}

package/dist/emit/report.d.ts

@@ -0,0 +1,2 @@
+import type { ConvertOptions, MigrationIR, ValidationResult } from "../ir.js";
+export declare function renderReport(ir: MigrationIR, options: ConvertOptions, validation?: ValidationResult): string;

package/dist/emit/report.js

@@ -0,0 +1,74 @@
+import { SDK_VERSION } from "../ir.js";
+import { markdown } from "./common.js";
+import { permissionWarning } from "../mapping/permissions.js";
+import { validationMessage } from "../validate.js";
+const statusLabels = {
+    zh: { mapped: "✅ 已映射", degraded: "⚠️ 降级", dropped: "❌ 丢弃" },
+    en: { mapped: "✅ Mapped", degraded: "⚠️ Degraded", dropped: "❌ Dropped" },
+};
+function allFindings(ir) {
+    const unique = new Map();
+    for (const finding of [...ir.findings, ...ir.agents.flatMap((a) => a.findings), ...ir.skills.flatMap((s) => s.findings)]) {
+        const key = JSON.stringify([finding.source, finding.field, finding.status, finding.message, finding.target]);
+        unique.set(key, finding);
+    }
+    // Defensive completeness: even callers constructing an IR manually cannot silently lose fields.
+    for (const asset of [...ir.agents, ...ir.skills]) {
+        for (const field of Object.keys(asset.frontmatter)) {
+            if (![...unique.values()].some((item) => item.source === asset.source && item.field === field)) {
+                const finding = {
+                    source: asset.source, field, status: "degraded",
+                    message: "没有可核实的自动映射结论。请对照原文件人工检查此字段；不要假定其运行时语义已保留。",
+                    messageEn: "No verified automatic mapping is available. Review this field against its source; do not assume its runtime semantics were preserved.",
+                };
+                unique.set(JSON.stringify([asset.source, field]), finding);
+            }
+        }
+    }
+    return [...unique.values()];
+}
+export function renderReport(ir, options, validation) {
+    const zh = options.lang === "zh";
+    const findings = allFindings(ir);
+    const rows = findings.map((finding) => `| ${markdown(finding.source)} | ${markdown(finding.field)} | ${statusLabels[options.lang][finding.status]} | ${markdown(finding.target ?? "—")} | ${markdown(zh ? finding.message : finding.messageEn)} |`);
+    const defaultValidation = { status: "skipped", command: "agent-sdk validate --dir <out>", message: zh ? "尚未执行。" : "Not run yet." };
+    const result = validation ?? defaultValidation;
+    const labels = zh ? { passed: "通过", failed: "失败", "dependencies-missing": "待安装依赖（未校验）", unavailable: "不可用", skipped: "未执行" } : { passed: "Passed", failed: "Failed", "dependencies-missing": "Dependencies missing (not validated)", unavailable: "Unavailable", skipped: "Skipped" };
+    const warning = permissionWarning(ir, options.lang);
+    return [
+        `# ${zh ? "迁移报告" : "Migration report"}: ${markdown(options.name)}`,
+        ...(warning ? ["", `**${markdown(warning)}**`] : []),
+        "", `agent2cursor → @grok/agent-sdk ${SDK_VERSION}`, "",
+        zh
+            ? `扫描结果：${ir.agents.length} 个子代理，${ir.skills.length} 个 skill（其中 ${ir.skills.filter((s) => s.dependency).length} 个依赖），${ir.scripts.length} 个禁用脚本工具存根。`
+            : `Inventory: ${ir.agents.length} subagents, ${ir.skills.length} skills (${ir.skills.filter((s) => s.dependency).length} dependencies), ${ir.scripts.length} disabled script-tool stubs.`,
+        "", `## ${zh ? "权限和执行边界" : "Permissions and execution boundaries"}`, "",
+        zh
+            ? "**原子代理的 tools / disallowedTools 限制无法在子代理层面保留。** 子代理共用父代理执行环境与 skills，子代理配置中的 tools 不受支持。不能假定根工具白名单能约束 task 子代理；请先验证，或禁用 task、拆成独立代理。只有显式传入 --root-tools 才会设置根代理工具白名单；不传时使用 SDK 默认工具。local.sandbox 已开启，但沙箱不等于只读；shell 可以写文件、执行命令。请在运行前审核实际权限。"
+            : "**Original per-subagent tools / disallowedTools restrictions cannot be preserved at subagent scope.** Subagents share the parent's execution environment and skills; subagent tools configuration is unsupported. Do not assume the root tool allowlist constrains task subagents. Verify that boundary, disable task, or use separate agents. Root tool restrictions are emitted only with explicit --root-tools; otherwise SDK defaults apply. local.sandbox is enabled, but a sandbox is not read-only; shell can write files and execute commands. Review actual permissions before running.",
+        "", zh
+            ? "原 skill 正文与辅助文件保留，可能仍包含其他平台的工具名或操作指令。迁移报告中的警告不会自动改写这些指令。scripts 文件只被复制，转换过程不会执行它们；生成的工具存根始终返回 TODO 错误。原脚本经审核并实现 JSON stdin/stdout 契约后才能启用。运行时 skill 路径是 .cursor/skills/<name>/，不是源码中的 bot/skills/<name>/。"
+            : "Original skill bodies and supporting files are preserved and may still refer to another platform's tools or operational instructions. Report warnings do not rewrite those instructions automatically. Scripts are copied, never executed during conversion; generated tool stubs always return a TODO error. Review original scripts and implement the JSON stdin/stdout contract before enabling them. Runtime skill paths are .cursor/skills/<name>/, not the source paths bot/skills/<name>/.",
+        "", zh
+            ? "工具名扫描使用固定名单，区分大小写匹配正文和附属 Markdown 中的标识符。未命中不表示工具兼容；命中也可能来自禁止调用的说明。请人工复核实际调用需求。"
+            : "Tool-name scanning uses a fixed, case-sensitive identifier list in bodies and supporting Markdown. No match does not establish compatibility; a match may occur in an instruction prohibiting a call. Review actual tool requirements manually.",
+        "", `## ${zh ? "逐文件、逐字段映射" : "Mapping by file and field"}`, "",
+        zh ? "| 源文件 | 字段 / 内容 | 结论 | 输出位置 | 说明与补救 |" : "| Source | Field / content | Result | Destination | Explanation and remedy |",
+        "| --- | --- | --- | --- | --- |", ...rows,
+        ...(rows.length ? [] : [zh ? "| — | — | ✅ 已映射 | — | 没有发现输入字段。 |" : "| — | — | ✅ Mapped | — | No input fields found. |"]),
+        "", `## ${zh ? "自动生成的 eval" : "Generated evals"}`, "",
+        zh
+            ? "每个 skill 生成 loadedSkill 用例，每个子代理生成 calledSubagent 用例。提示要求按源说明做一个最小例子，用来检查是否加载了对应 skill、是否委派给对应子代理；不要求模型忽略自己的说明。这些用例不证明能力或安全性。未运行真实模型时，不能称为 eval 通过。禁用脚本存根不生成成功调用用例；实现后请补充 calledTool 和结果断言。"
+            : "Each skill receives a loadedSkill case; each subagent receives a calledSubagent case. The prompt asks for one minimal example that follows the source instructions, so the case checks that the named skill was loaded or the named subagent was called. It does not ask the model to ignore those instructions. These cases do not prove capability or safety and are not passing evals until run against a real model. Disabled script stubs do not receive successful-call cases; add calledTool and result assertions after implementation.",
+        "", `## ${zh ? "SDK 自检" : "SDK validation"}`, "",
+        `- ${zh ? "状态" : "Status"}: ${labels[result.status]}`,
+        `- ${zh ? "命令" : "Command"}: ${markdown(result.command)}`,
+        `- ${zh ? "结果" : "Result"}: ${markdown(validationMessage(result, options.lang))}`,
+        ...(result.diagnostics ?? []).map((diagnostic) => `- ${markdown(diagnostic.severity)}: ${markdown(diagnostic.message)}`),
+        "", zh
+            ? "validate 只检查项目结构与配置；它不验证模型 ID 是否可用，也不证明真实模型执行、GitHub 触发或部署成功。"
+            : "validate checks project structure and configuration only; it does not establish model-ID availability, live model execution, GitHub triggers, or successful deployment.",
+        "", `## ${zh ? "下一步" : "Next steps"}`, "",
+        "```sh", "npm install", "npx agent-sdk validate --dir .", "npx agent-sdk eval --dir . --list", "npx agent-sdk login", "npx agent-sdk dev", "```", "",
+    ].join("\n");
+}

package/dist/emit/subagent.d.ts

@@ -0,0 +1,2 @@
+import type { AgentAsset, ConvertOptions } from "../ir.js";
+export declare function renderSubagent(agent: AgentAsset, options: ConvertOptions): string;

package/dist/emit/subagent.js

@@ -0,0 +1,15 @@
+import { assertId, literal, todo } from "./common.js";
+export function renderSubagent(agent, options) {
+    assertId(agent.id, "subagent");
+    const notes = agent.findings.filter((finding) => finding.status !== "mapped")
+        .map((finding) => todo(`${finding.field}: ${options.lang === "zh" ? finding.message : finding.messageEn}`));
+    return [
+        '// Generated by agent2cursor. Review the migration report before running.',
+        'import { defineAgent } from "@grok/agent-sdk";',
+        "", "export default defineAgent({",
+        `  description: ${literal(agent.description)},`,
+        ...(agent.model ? [`  model: ${literal(agent.model)},`] : []),
+        ...notes,
+        "});", "",
+    ].join("\n");
+}

package/dist/emit/tool-stub.d.ts

@@ -0,0 +1,3 @@
+import type { ConvertOptions, ScriptAsset } from "../ir.js";
+export declare const DISABLED_TOOL_SCRIPT: string;
+export declare function renderToolStub(script: ScriptAsset, options: ConvertOptions): string;

package/dist/emit/tool-stub.js

@@ -0,0 +1,29 @@
+import { assertId, literal, todo } from "./common.js";
+// Constant shell source: no original file contents or source-controlled paths are executable.
+export const DISABLED_TOOL_SCRIPT = [
+    "#!/usr/bin/env sh",
+    "# Disabled by agent2cursor. Review the original script and implement the JSON contract first.",
+    "cat >/dev/null",
+    "printf '%s\\n' '{\"ok\":false,\"error\":\"AGENT2CURSOR_STUB_DISABLED\",\"message\":\"TODO(agent2cursor): review the original script and implement JSON stdin/stdout before enabling this tool.\"}'",
+    "exit 78",
+    "",
+].join("\n");
+export function renderToolStub(script, options) {
+    assertId(script.id, "tool");
+    assertId(script.skillId, "skill");
+    const description = options.lang === "zh"
+        ? `禁用的迁移存根 ${script.id}。调用始终返回 AGENT2CURSOR_STUB_DISABLED，绝不执行原脚本。请操作者先审查 .cursor/skills/${script.skillId}/${script.relativePath} 并实现 JSON 输入输出契约。`
+        : `Disabled migration stub ${script.id}. Always returns AGENT2CURSOR_STUB_DISABLED and never runs the original script. An operator must review .cursor/skills/${script.skillId}/${script.relativePath} and implement the JSON input/output contract first.`;
+    return [
+        'import { defineTool } from "@grok/agent-sdk/tools";',
+        'import { z } from "zod";', "",
+        "export default defineTool({",
+        `  description: ${literal(description)},`,
+        '  execution: "agent",',
+        todo(options.lang === "zh" ? "按审核后的脚本参数收紧 schema；当前存根不会运行任何原脚本。" : "Replace this permissive schema with reviewed script arguments; the stub never runs original scripts."),
+        "  inputSchema: z.object({}).passthrough(),",
+        todo(options.lang === "zh" ? "agent 工具必须通过 shell 执行，不支持 effect / dryRunResult / needsApproval；需要这些保护时请实现 server 工具。" : "Agent tools require shell and do not support effect / dryRunResult / needsApproval; use a server tool when those controls are required."),
+        `  script: ${literal(DISABLED_TOOL_SCRIPT)},`,
+        "});", "",
+    ].join("\n");
+}

package/dist/emit/tstack-license.d.ts

@@ -0,0 +1,8 @@
+import type { SkillAsset } from "../ir.js";
+export interface TstackLicense {
+    root: string;
+    source: string;
+    bytes: Buffer;
+    sha256: string;
+}
+export declare function associatedTstackLicense(skill: SkillAsset): Promise<TstackLicense | undefined>;

package/dist/emit/tstack-license.js

@@ -0,0 +1,39 @@
+import { createHash } from "node:crypto";
+import { lstat } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { readSafeFile, readSafeText } from "../scan/safety.js";
+// Public MIT license at t3dotgg/tstack commit 7de017b3fc9d50c03cf3ecb98fb71e0ca65a78bd.
+// No SDK implementation or documentation is vendored by this check.
+const TSTACK_LICENSE_SHA256 = "8095f9a9f97d074131f6a2ce09b952d12c18b36f09f4e5df0517c4e64e82c851";
+export async function associatedTstackLicense(skill) {
+    const skillsDirectory = dirname(skill.directory);
+    if (basename(skillsDirectory) !== "skills")
+        return undefined;
+    const root = dirname(skillsDirectory);
+    const readmePath = join(root, "README.md");
+    try {
+        await lstat(readmePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const readme = await readSafeText(readmePath);
+    if (!/^#\s+tstack\s*$/mu.test(readme) || !readme.includes("t3dotgg/tstack"))
+        return undefined;
+    const source = join(root, "LICENSE");
+    let bytes;
+    try {
+        bytes = await readSafeFile(source, 16 * 1024);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            throw new Error(`Recognized tstack source is missing its MIT LICENSE: ${root}`);
+        throw error;
+    }
+    const normalizedHash = createHash("sha256").update(bytes.toString("utf8").replaceAll("\r\n", "\n")).digest("hex");
+    if (normalizedHash !== TSTACK_LICENSE_SHA256)
+        throw new Error(`Recognized tstack LICENSE differs from the verified MIT notice. Review its license before conversion: ${source}`);
+    return { root, source, bytes, sha256: createHash("sha256").update(bytes).digest("hex") };
+}

package/dist/ir.d.ts

@@ -0,0 +1,66 @@
+export declare const SDK_VERSION = "0.3.0";
+export type Language = "zh" | "en";
+export type Status = "mapped" | "degraded" | "dropped";
+export interface Finding {
+    source: string;
+    field: string;
+    status: Status;
+    message: string;
+    messageEn: string;
+    target?: string;
+}
+export interface AgentAsset {
+    id: string;
+    source: string;
+    sourceFormat?: "claude" | "codex";
+    body: string;
+    frontmatter: Record<string, unknown>;
+    description: string;
+    model?: string;
+    findings: Finding[];
+}
+export interface SkillAsset {
+    id: string;
+    source: string;
+    directory: string;
+    body: string;
+    frontmatter: Record<string, unknown>;
+    description: string;
+    trigger?: string;
+    dependency: boolean;
+    findings: Finding[];
+}
+export interface ScriptAsset {
+    id: string;
+    source: string;
+    skillId: string;
+    relativePath: string;
+}
+export interface MigrationIR {
+    agents: AgentAsset[];
+    skills: SkillAsset[];
+    scripts: ScriptAsset[];
+    findings: Finding[];
+}
+export interface ConvertOptions {
+    name: string;
+    lang: Language;
+    withDeps: boolean;
+    keepModel: boolean;
+    modelMap: Record<string, string>;
+    rootTools?: string[];
+}
+export interface ValidationResult {
+    status: "passed" | "failed" | "dependencies-missing" | "unavailable" | "skipped";
+    command: string;
+    message: string;
+    missingDependencies?: string[];
+    diagnostics?: {
+        severity: string;
+        message: string;
+    }[];
+}
+export interface ProjectPlan {
+    files: Map<string, string | Buffer>;
+    ir: MigrationIR;
+}

package/dist/ir.js

@@ -0,0 +1 @@
+export const SDK_VERSION = "0.3.0";

package/dist/mapping/codex-agent.d.ts

@@ -0,0 +1,2 @@
+import type { AgentAsset, ConvertOptions } from "../ir.js";
+export declare function mapCodexAgent(source: string, config: Record<string, unknown>, options: ConvertOptions): AgentAsset;

package/dist/mapping/codex-agent.js

@@ -0,0 +1,39 @@
+import { fieldPaths } from "../scan/frontmatter.js";
+import { mapSubagent } from "./subagent.js";
+export function mapCodexAgent(source, config, options) {
+    const core = { name: config.name, description: config.description,
+        ...(Object.hasOwn(config, "model") ? { model: config.model } : {}) };
+    const asset = mapSubagent(source, { frontmatter: core, body: config.developer_instructions }, options);
+    asset.sourceFormat = "codex";
+    asset.frontmatter = config;
+    // Reuse the shared name/model/body mappings, not Claude-specific field semantics.
+    for (const [key, value] of Object.entries(config)) {
+        if (Object.hasOwn(core, key))
+            continue;
+        let rule = { source, status: "dropped",
+            message: "目标 SDK 无已核实的 Codex 等价字段；未写入配置，请人工实现其语义。",
+            messageEn: "No verified SDK equivalent for this Codex field; omitted from configuration. Implement its semantics manually." };
+        if (key === "developer_instructions")
+            rule = { source, status: "mapped", target: `bot/subagents/${asset.id}/instructions.md`,
+                message: "TOML 指令字符串已写入 instructions.md；保留解析后的文本，不包含 TOML 引号。",
+                messageEn: "Wrote the parsed TOML instruction string to instructions.md unchanged, without TOML quoting." };
+        if (["model_reasoning_effort", "model_reasoning_summary", "model_verbosity"].includes(key))
+            rule = { source, status: "dropped",
+                message: "Codex 模型参数未映射；模型 ID 映射不包含推理强度、摘要或详细度。请按目标模型支持的参数人工配置并验证。",
+                messageEn: "Codex model settings were not mapped; model-ID mapping does not include reasoning effort, summary, or verbosity. Configure and verify supported target-model parameters manually." };
+        if (["features", "skills", "tools", "disallowedTools"].includes(key))
+            rule = { source, status: "degraded",
+                message: "Codex 子代理能力或 skill 限制未生效；SDK 子代理共享执行环境和 skills，不能假定根白名单会约束 task 子代理。请人工重建限制，必要时拆为独立代理或禁用 task。未加载任何引用的配置或 skill 文件。",
+                messageEn: "Codex per-agent capability or skill restrictions are not enforced. SDK subagents share the execution environment and skills; do not assume root allowlists constrain task children. Rebuild restrictions manually, use separate agents, or disable task. No referenced configuration or skill files were loaded." };
+        if (["sandbox_mode", "approval_policy", "sandbox_workspace_write", "permissions", "model_provider", "mcp_servers", "service_tier"].includes(key))
+            rule = { source, status: "dropped",
+                message: "这是父会话配置，不是 Codex 独立子代理的有效覆盖项；未迁移父会话的权限、provider 或 MCP 连接。请在目标项目人工配置并验证，local.sandbox 不等于原有权限边界。",
+                messageEn: "This is parent-session configuration, not an effective standalone Codex agent override. Parent permissions, provider, and MCP connections were not migrated. Configure and verify them in the target project; local.sandbox is not an equivalent permission boundary." };
+        for (const field of fieldPaths({ [key]: value }))
+            asset.findings.push({ ...rule, field });
+    }
+    asset.findings.push({ source, field: "$context", status: "degraded",
+        message: "仅迁移独立子代理文件；未读取父会话 config.toml、AGENTS.md 或个人配置，未解析旧式 agents.<name>.config_file。请一并转换所需 skills，并人工补充上下文。",
+        messageEn: "Only the standalone agent file is migrated. Parent config.toml, AGENTS.md, personal configuration, and legacy agents.<name>.config_file declarations are not loaded. Convert required skills and add inherited context manually." });
+    return asset;
+}

package/dist/mapping/codex-skill.d.ts

@@ -0,0 +1,5 @@
+import type { Finding } from "../ir.js";
+export declare function mapCodexSkillMetadata(source: string, metadata: Record<string, unknown>, skillId: string): {
+    trigger?: string;
+    findings: Finding[];
+};

package/dist/mapping/codex-skill.js

@@ -0,0 +1,32 @@
+import { fieldPaths } from "../scan/frontmatter.js";
+import { scanForeignTools } from "./foreign-tools.js";
+export function mapCodexSkillMetadata(source, metadata, skillId) {
+    const ui = metadata.interface;
+    const rawTrigger = ui && typeof ui === "object" && !Array.isArray(ui) ? ui.default_prompt : undefined;
+    const trigger = typeof rawTrigger === "string" && rawTrigger.trim() ? rawTrigger : undefined;
+    const copied = `bot/skills/${skillId}/agents/openai.yaml`;
+    const findings = fieldPaths(metadata).map(field => {
+        const base = { source, field, status: "degraded", target: copied };
+        if (field === "interface.default_prompt")
+            return { ...base, status: trigger ? "mapped" : "degraded", target: "evals/skills.eval.ts",
+                message: trigger ? "已用 Codex default_prompt 生成 eval 触发语；不改写其中的平台工具或路径引用。" : "未发现有效 default_prompt，将使用生成的 eval 触发语。",
+                messageEn: trigger ? "Used Codex default_prompt as the eval trigger; platform-specific tool and path references are not rewritten." : "No valid default_prompt found; using a generated eval trigger." };
+        if (field === "policy" || field.startsWith("policy."))
+            return { ...base,
+                message: "仅保留调用策略元数据；SDK 不执行 Codex policy，包括 allow_implicit_invocation: false 的禁止自动调用语义。需人工限制触发流程；复制不保留此边界。",
+                messageEn: "Invocation policy is retained as metadata only. The SDK does not enforce Codex policy, including the implicit-invocation restriction of allow_implicit_invocation: false. Constrain routing manually; copying does not preserve this boundary." };
+        if (field === "dependencies" || field.startsWith("dependencies."))
+            return { ...base,
+                message: "仅保留工具依赖声明；未连接 MCP、安装工具或转移认证。请在 bot/mcp-connections/ 人工配置所需连接，并核对名称、传输方式与权限。",
+                messageEn: "Tool dependencies are declarations only; no MCP connections, tools, or authentication were installed or transferred. Configure required connections in bot/mcp-connections/ and verify names, transport, and permissions." };
+        return { ...base,
+            message: "仅原样保留 Codex 元数据文件；目标 SDK 未应用此 UI 或未知字段，需人工适配。",
+            messageEn: "Preserved as Codex metadata only; the target SDK does not apply this UI or unknown field. Adapt it manually." };
+    });
+    if (!findings.some(finding => finding.field === "interface.default_prompt"))
+        findings.push({ source, field: "interface.default_prompt", status: "degraded", target: "evals/skills.eval.ts",
+            message: "未发现有效 default_prompt，将使用生成的 eval 触发语。", messageEn: "No valid default_prompt found; using a generated eval trigger." });
+    if (trigger)
+        findings.push(...scanForeignTools(trigger, source));
+    return { trigger, findings };
+}

package/dist/mapping/foreign-tools.d.ts

@@ -0,0 +1,2 @@
+import type { Finding } from "../ir.js";
+export declare function scanForeignTools(body: string, source: string): Finding[];