@kyun.si/agent2cursor 0.0.0-stage → 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing and Maintainer Guide
+
+This document covers local development, verification workflows, demo regeneration, and repository safety rules for `agent2cursor`. For user-facing usage and migration behavior, see [README.md](README.md) ([中文说明](README.zh-CN.md)).
+
+## Prerequisites
+
+- **Node.js `>=22.13`** (enforced at CLI startup and in `package.json`).
+- **npm** (used with `package-lock.json`).
+
+Offline unit tests and fixture conversions do not require a Cursor account or network access.
+
+## Project Naming
+
+The public npm package is `@kyun.si/agent2cursor`. Use `agent2cursor` for the executable, generated-code notices, demo names, and repository links. The source workspace keeps `private: true`; the consumer archive omits it. The old executable name is not installed as an alias. Demo workspace snapshots use `.agent2cursor/pr-review.json`, disabled script stubs return `AGENT2CURSOR_STUB_DISABLED`, and the optional merge gate uses `AGENT2CURSOR_ALLOW_MERGE` (disabled by default).
+
+Historical evaluation reports and hash-bound evidence retain the names and paths used by those runs. Do not rewrite them to imply the current sources were evaluated.
+
+## Build and Unit Tests
+
+Run the TypeScript compiler and the automated tests before delivering changes:
+
+```bash
+npm ci --ignore-scripts
+npm run check
+```
+
+Individual scripts defined in [package.json](package.json):
+
+| Command | Purpose |
+| --- | --- |
+| `npm run build` | Compile TypeScript (`src/` to `dist/`) via `tsc` |
+| `npm test` | Run the test suite (`tsx --test test/*.test.ts`) |
+| `npm run check` | Run `npm run build && npm test` |
+| `npm run dev -- <args>` | Run `src/cli.ts` directly via `tsx` |
+| `npm run test:sdk` | Run structural SDK verification via `scripts/verify-sdk.mjs` |
+
+## Structural SDK Verification (`.validation/`)
+
+SDK integration tests install `@grok/agent-sdk@0.3.0` into the gitignored `.validation/` directory and invoke only its public CLI (`validate`, `info`, `eval --list`), followed by strict TypeScript typechecking on generated projects:
+
+```bash
+npm run build
+npm install --prefix .validation --ignore-scripts --no-audit --no-fund @grok/agent-sdk@0.3.0
+npm run test:sdk
+```
+
+Never vendor SDK source code or bundled SDK documentation into the repository.
+
+Generated projects live in system temporary directories outside this checkout. The check verifies default conversion and a failing `doctor` before installing each project's own dependencies without lifecycle scripts, then runs validation, strict TypeScript and eval discovery. Do not generate these projects under `.validation/`: its dependencies would mask first-run failures. Sanitized evidence stays in `.validation/acceptance-*/`.
+
+## Regenerating Demos
+
+The two demos ([demos/full-send](demos/full-send) and [demos/pr-review](demos/pr-review)) are generated from the pinned [t3dotgg/tstack](https://github.com/t3dotgg/tstack) MIT snapshot in [fixtures/tstack](fixtures/tstack) (`7de017b3fc9d50c03cf3ecb98fb71e0ca65a78bd`) and templates in `scripts/demo-templates/`:
+
+```bash
+node scripts/build-demos.mjs
+```
+
+After regenerating demos, run `npm run check` to verify that provenance hashes, license files (`LICENSE-tstack`), and channel/snapshot templates remain in sync.
+
+## npm Release
+
+The public GitHub repository and the npm registry are separate destinations. Keep the source workspace private to npm with `private: true`. `pack:local` builds a clean consumer archive named `kyun.si-agent2cursor-<version>.tgz` under `.validation/npm-release/`, with the scoped package name, public access, the official registry, and the source Git revision. The archive contains the explicit `files` allowlist and omits development dependencies and lifecycle scripts.
+
+```bash
+npm run check
+npm run pack:local
+npm run publish:npm -- --dry-run
+npm run publish:npm
+```
+
+Before the real publish, install the archive into an independent consumer and verify the actual `agent2cursor` executable, conversion, demos, and doctor. `publish:npm` verifies the recorded source hashes, Git revision, archive size and SHA-256, and publishes that same archive without repacking. Any changed input requires rebuilding and rechecking. Login and two-factor authentication stay in npm's own flow; no credentials belong in source or evidence.
+
+After publication, read the registry metadata and download its tarball anonymously. Verify SHA-256 and registry integrity against the candidate, then install `@kyun.si/agent2cursor@<version>` from the public registry into a clean consumer and repeat the CLI checks. Record the public metadata and verification results in `npm-publication.json`. Do not claim publication before this readback succeeds.
+
+## Evaluation Evidence
+
+Keep tests, demo eval suites and source fixtures with the implementation. [evaluation/README.md](evaluation/README.md) indexes the independent evaluation; `docs/evidence/` contains bounded, portable summaries. Local raw runs, generated projects and deployment workspaces are ignored. Preserve those artifacts locally when they are needed for an audit; do not stage them with a blanket `git add`.
+
+The maintained demo projects live only in `demos/`. Create personal deployment copies outside the repository or in the ignored `deployments/` directory. The README animation retains its editable source under `docs/demo-video/` and final media under `docs/assets/`.
+
+## Repository Rules and Safety Invariants
+
+1. **Account for every source field.** Every YAML frontmatter, Codex agent TOML, and `agents/openai.yaml` field path must appear in `MIGRATION.zh-CN.md` / `MIGRATION.en.md` as `mapped`, `degraded`, or `dropped`.
+2. **Never silently expand permissions.** Do not claim a root `tools` allowlist isolates `task` subagents, and never describe an agent with `shell` enabled as read-only.
+3. **Keep script tools disabled by default.** Source scripts under `skills/*/scripts/*` are copied without execution bits, and generated `bot/tools/*.ts` wrappers must remain disabled stubs (`AGENT2CURSOR_STUB_DISABLED`) until an operator implements a typed JSON stdin/stdout contract.
+4. **Safe filesystem handling.** Conversion must never execute source scripts, overwrite existing output directories, traverse symlinks, or read/copy credential files (`.env`, `.npmrc`, private keys, or sensitive YAML keys).
+5. **Keep evidence levels separate.** Do not conflate unit tests or `agent-sdk validate` / `eval --list` with live model execution, real GitHub webhook delivery, hosted deployment, or npm publication. See [docs/acceptance.md](docs/acceptance.md) and [docs/upstream-verification.md](docs/upstream-verification.md).
+6. **Credential-safe diagnostics.** Never write raw process `argv`, environment dumps, authentication files, or unfiltered runtime logs into diagnostics, tests, or committed evidence files.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eason Yang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,203 @@
-# Temporary Holding Version
+# agent2cursor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Convert existing Claude Code and Codex subagents and Agent Skills into editable [Cursor Agent SDK](https://cursor.com/docs/agent-sdk) (`@grok/agent-sdk`) TypeScript projects, with routing eval scaffolds and a field-by-field migration report.
+
+[中文说明](README.zh-CN.md) · **0.1.0** · [MIT License](LICENSE) · Node **>=22.13** · Targets **`@grok/agent-sdk@0.3.0`**
+
+![Converting Claude subagents and skills into an Agent SDK project with a field-by-field migration report](docs/assets/agent2cursor-demo.gif)
+
+If you already wrote subagents in `.claude/agents/*.md` or `.codex/agents/*.toml`, or skill folders containing `SKILL.md` (including [t3dotgg/tstack](https://github.com/t3dotgg/tstack) workflows), `agent2cursor` turns those loose files into a standalone Cursor Agent SDK project. It generates editable source files, a per-field migration report, and initial routing evals—it does **not** migrate underlying models or chat history, and it does **not** guarantee preserved runtime behavior or subagent permission boundaries.
+
+```text
+.claude/agents/code-reviewer.md → bot/subagents/code-reviewer/{agent.ts,instructions.md}
+.codex/agents/reviewer.toml     → bot/subagents/<name>/{agent.ts,instructions.md}
+skills/<name>/SKILL.md          → bot/skills/<name>/SKILL.md
+skills/*/scripts/*              → bot/tools/*.ts (disabled JSON adapter stubs)
+source fields + routing checks  → MIGRATION.zh-CN.md (or .en.md) + evals/*.eval.ts
+```
+
+## Quickstart
+
+The npm package name is **`@kyun.si/agent2cursor`**; the executable is **`agent2cursor`**:
+
+```bash
+npx --yes @kyun.si/agent2cursor@0.1.0 --help
+npm install --global @kyun.si/agent2cursor@0.1.0
+agent2cursor inspect .claude/agents
+agent2cursor convert .claude/agents --out ./my-agent
+```
+
+Pass paths that exist on your machine. Codex inputs can use `.codex/agents` and `.agents/skills`; Claude and Codex inputs can also be combined. Conversion is local and does not require a Cursor account.
+
+To try the included [`fixtures/`](fixtures/claude) instead, build from a source checkout:
+
+```bash
+npm ci --ignore-scripts
+npm run build
+
+# Inspect or convert the checked-in Claude subagents + tstack full-send skill closure
+node dist/cli.js inspect ./fixtures/claude ./fixtures/tstack/skills/full-send --with-deps --lang en
+node dist/cli.js convert ./fixtures/claude ./fixtures/tstack/skills/full-send \
+  --with-deps --lang en --out /tmp/my-agent
+```
+
+```text
+⚠️ Source subagent restrictions are not enforced (4 affected): tools / disallowedTools / permissionMode were not migrated. SDK validation does not establish read-only access; --root-tools sets only the root allowlist.
+agent2cursor v0.1.0 → @grok/agent-sdk 0.3.0
+Scanned: 4 agents, 5 skills, 1 script stubs
+...
+```
+
+On this fixture input (4 subagents, 5 skills including 4 `tstack` dependencies, and 1 script stub), `agent2cursor` writes **28 files** and lists migration concerns in `/tmp/my-agent/MIGRATION.en.md`. Exact concern counts and `Validation` status depend on your inputs, flags, and installed dependencies (`dependencies-missing` is expected before installing dependencies in `/tmp/my-agent`).
+
+To install the SDK inside the generated project and run structural checks from this checkout:
+
+```bash
+(cd /tmp/my-agent && npm install && npx agent-sdk validate --dir . && npx agent-sdk eval --dir . --list)
+node dist/cli.js doctor --dir /tmp/my-agent
+```
+
+Maintainers build the public archive with `npm run pack:local` and publish that exact verified archive with `npm run publish:npm`; see [CONTRIBUTING.md](CONTRIBUTING.md#npm-release). The source workspace keeps `private: true`; the public archive omits that field.
+
+- **SDK package name:** [Official Cursor Agent SDK docs](https://cursor.com/docs/agent-sdk) specify **`@grok/agent-sdk`** (formerly `@cursor/bdk`). Do not substitute `@cursor/agent-sdk` from older blog posts; see [upstream verification](docs/upstream-verification.md). Generated `package.json` pins `@grok/agent-sdk` to `0.3.0` and declares `zod` `^3.25.0`.
+- **Account requirements by step:**
+  1. **Offline conversion & structural checks** (`convert`, `inspect`, `doctor`, `agent-sdk validate`, `agent-sdk eval --list`) require **no** Cursor account or API key.
+  2. **Live model execution** (`agent-sdk dev`, `agent-sdk run`, live `agent-sdk eval`) requires `agent-sdk login` and model access on your Cursor account.
+  3. **Cloud hosting** (`agent-sdk deploy`) is optional and requires an account/team with hosting enabled and repository permissions.
+
+`convert` and `demo` exit 0 when files are written but declared SDK or `zod` dependencies are missing: `validation.status` is `dependencies-missing`, with the missing package names. Validation has not run. Install dependencies and run `agent2cursor doctor --dir <project>`; `doctor` exits nonzero until validation passes. Actual validation errors still make conversion exit 1. Dependencies are never installed automatically.
+
+## Convert Codex assets
+
+After building the checkout, pass project or personal agent directories, a standalone TOML file, and/or skill directories. Claude and Codex inputs can be mixed in one conversion:
+
+```bash
+node dist/cli.js inspect .codex/agents .agents/skills --lang en
+node dist/cli.js convert .codex/agents .agents/skills --out ./my-codex-agent --lang en
+# Included synthetic example: no Codex installation or account required
+node dist/cli.js convert fixtures/codex/project --out /tmp/codex-example --lang en
+```
+
+Use only paths that exist; either input can be used alone. Personal standalone agents under `~/.codex/agents` are also accepted. A project root discovers these agent trees and skill folders, while unrelated TOML files are ignored.
+
+| Codex input | Conversion |
+| --- | --- |
+| Standalone `name`, `description`, `developer_instructions` | Required non-empty strings; generates subagent ID, delegation description, and the parsed instruction text. Invalid files fail explicitly. |
+| `model` | Inherits the target parent by default. Use `--model-map source-id=target-id` or `--keep-model`; availability is not established by validation. |
+| `model_reasoning_effort`, `model_reasoning_summary`, `model_verbosity` | Reported as dropped; model-ID mapping does not migrate these parameters. |
+| `features.*`, `skills.*` | Reported as degraded; per-agent capability and skill restrictions are not enforced. Referenced skill paths are not read. |
+| Parent settings, including sandbox, approval, provider, and MCP | Not imported. These do not override the parent in a standalone Codex agent either. Configure the target environment explicitly. |
+| `agents/openai.yaml` | Copied unchanged. A valid `interface.default_prompt` becomes an eval trigger; every UI, policy, dependency, and unknown field receives a migration entry. Invocation policy is not enforced and MCP dependencies are not connected. |
+
+This supports **standalone Codex TOML agents → Cursor Agent SDK**, not whole-session migration or output for Codex. Parent `config.toml`, `AGENTS.md`, credentials, and legacy `[agents.<name>] config_file` declarations are not imported. Inherited instructions, tools, and skills must be reviewed separately. Codex tool references receive suggestions without automatic prompt rewriting. See the [Codex fixtures](fixtures/codex) and [verified scope](docs/upstream-verification.md#codex-input-adapter-2026-10-28).
+
+## When to Use agent2cursor
+
+`@grok/agent-sdk` already supports native skills and plugins. Choose the lightest path that fits your assets:
+
+| Approach | When to use it |
+| --- | --- |
+| Copy `SKILL.md` directly | You only have compatible `SKILL.md` directories and do not need subagent conversion, script stubs, or a migration report |
+| SDK `cursorPlugin()` | You have a Cursor/Claude plugin manifest and runtime mounting is enough |
+| `agent-sdk init --from automation:` / `migrate` | You are migrating a Cursor Automation or upgrading an older SDK project |
+| **`agent2cursor`** | You hold loose Claude `.md` / Codex `.toml` agents, skill directories, or `tstack` workflows and want editable SDK source, field-by-field loss accounting, foreign-tool warnings, disabled script stubs, and routing eval scaffolds |
+
+## What Gets Migrated (Example: `code-reviewer`)
+
+Given [`fixtures/claude/agents/code-reviewer.md`](fixtures/claude/agents/code-reviewer.md):
+
+```markdown
+---
+name: code-reviewer
+description: Review changed code for defects, maintainability, and missing verification.
+tools: Read, Grep, Glob
+model: sonnet
+---
+Review the changed code. Prioritize concrete defects and cite the affected file and line.
+Do not edit files. Explain what was verified and what remains uncertain.
+```
+
+`agent2cursor convert` emits `bot/subagents/code-reviewer/agent.ts`, writes the prompt body to `bot/subagents/code-reviewer/instructions.md`, and logs every frontmatter field in `MIGRATION.zh-CN.md` (or `MIGRATION.en.md`):
+
+```ts
+// bot/subagents/code-reviewer/agent.ts
+// Generated by agent2cursor. Review the migration report before running.
+import { defineAgent } from "@grok/agent-sdk";
+
+export default defineAgent({
+  description: "Review changed code for defects, maintainability, and missing verification.",
+  // TODO(agent2cursor): tools: Security boundary lost: task children retain the harness task-tool toolset; do not assume root allowlists constrain them. Reference name mapping (read, grep, glob). For enforced read-only access use separate agents or disable task and constrain execution separately; shell can write.
+  // TODO(agent2cursor): model: Omitted model to inherit the parent model; use --model-map to select a target model explicitly.
+});
+```
+
+<details>
+<summary><strong>Field-by-field disposition reference</strong></summary>
+
+| Source asset or field | SDK output location | Disposition | Behavior |
+| --- | --- | --- | --- |
+| Subagent `name` | `bot/subagents/<id>/` | `✅ Mapped` / `⚠️ Degraded` | `✅` when already a valid slug; `⚠️` when normalized or derived from the filename |
+| Subagent `description` | `bot/subagents/<id>/agent.ts` | `✅ Mapped` / `⚠️ Degraded` | `✅` when non-empty; `⚠️` with a generated placeholder when missing or blank |
+| Subagent Markdown body | `bot/subagents/<id>/instructions.md` | `✅ Mapped` / `⚠️ Degraded` | Unchanged bodies are mapped; appending a shared-skill preload hint is explicitly reported as degraded, with the original text retained |
+| Subagent `model` | `bot/subagents/<id>/agent.ts` | `✅ Mapped` / `⚠️ Degraded` | `inherit` is omitted (`✅`). Other IDs (`sonnet`, `opus`, `haiku`) are omitted by default (`⚠️`) to inherit the parent model unless mapped with `--model-map` (`✅`) or kept with `--keep-model` (`⚠️`) |
+| Subagent `tools` / `disallowedTools` | `MIGRATION.*.md` + `TODO(agent2cursor)` | `⚠️ Degraded` | Per-subagent tool lists are unsupported in SDK `0.3.0`; `task` children retain the harness `task` toolset |
+| Subagent `skills` | `bot/instructions.md` + `instructions.md` | `⚠️ Degraded` | Emits shared-skill loading hints (no native per-subagent preloading) |
+| `permissionMode`, `hooks`, `mcpServers`, `memory`, unknown agent fields | `MIGRATION.*.md` + `TODO(agent2cursor)` | `❌ Dropped` | No verified 1:1 SDK equivalent; documented in the report for manual implementation |
+| `SKILL.md` + supporting files | `bot/skills/<id>/**` | `✅ Mapped` / `⚠️ Degraded` | Keeps body, supporting files, and extra frontmatter (`license`, `metadata.*`); `name`/`description` degrade to `⚠️` if normalized/missing, and `allowed-tools` is marked `⚠️` |
+| `skills/*/agents/openai.yaml` | Copied metadata + `evals/skills.eval.ts` | `✅ Mapped` / `⚠️ Degraded` | Valid `interface.default_prompt` becomes an eval trigger; UI, invocation policy, tool dependencies, and unknown fields are reported individually as metadata without SDK runtime semantics |
+| `skills/*/scripts/*` | `bot/skills/<id>/scripts/*` + `bot/tools/<script>.ts` | `⚠️ Degraded` | Copies script without executable bits and emits a disabled `execution: "agent"` stub (`AGENT2CURSOR_STUB_DISABLED`) |
+
+</details>
+
+## CLI Reference
+
+| Command or flag | Description |
+| --- | --- |
+| `convert <input...>` | Convert Claude `.md` / standalone Codex `.toml` files, `.claude/agents/` / `.codex/agents/` trees, skill directories, or a `tstack` repo into a new SDK project |
+| `inspect <input...>` | Print the migration report (or `--json` summary) without writing files |
+| `demo <full-send\|pr-review>` | Export one of the two adapted `tstack` demo projects (`--out <dir>`, `--json`, `--no-validate`) |
+| `doctor [--dir <project>]` | Check Node `>=22.13` and run `agent-sdk validate` with credential-safe diagnostic summaries |
+| `--out <dir>` | New output directory for `convert` (default `./my-agent`; never overwrites existing paths) |
+| `--name <name>` | Generated agent name (`1–64` lowercase letters, digits, `-`, or `_`, starting with a letter or digit; default `converted-agent`) |
+| `--lang <zh\|en>` | Language for generated instructions, eval prompts, and `MIGRATION.zh-CN.md` / `MIGRATION.en.md` (default `zh`) |
+| `--with-deps` | Include sibling skills required by the `tstack` dependency graph |
+| `--model-map <map>` | Map source models explicitly, e.g. `--model-map sonnet=<account-verified-id>` (verify ID availability on your account) |
+| `--keep-model` | Keep unverified source model IDs as-is instead of omitting them to inherit |
+| `--root-tools <list>` | Explicit root allowlist (`read,grep,glob,ls,shell,edit,task,delete`); omitting preserves SDK defaults |
+| `--dry-run` / `--no-validate` / `--json` | Plan `convert` without writing files / skip `agent-sdk validate` / print machine-readable JSON |
+
+## Included Demos
+
+Both demos are adapted in Chinese from a pinned [t3dotgg/tstack](https://github.com/t3dotgg/tstack) MIT snapshot (`7de017b3fc9d50c03cf3ecb98fb71e0ca65a78bd`) and include `LICENSE-tstack` and `TSTACK-PROVENANCE.json`. Export them with `node dist/cli.js demo <full-send|pr-review> --out <dir>`:
+
+- **`full-send` ([operation guide](demos/full-send/README.md)):** five skills (`full-send`, `sol-loop`, `file-pr`, `babysit-pr`, `leaving-pr-comments`), a `reviewer` subagent, a one-shot read-only `pr_wait` snapshot tool (no polling), a disabled `pr_wait_script` stub alongside the retained Python `pr-wait` script, and a gated `merge_pr` tool. Its root tools exclude `shell`, so **it prepares local edits and a PR draft and stops before publishing or merging**—automatic test execution, `git push`, and PR creation are not implemented. `merge_pr` is off by default and requires `AGENT2CURSOR_ALLOW_MERGE=1`, human approval, a matching configured GitHub session, an open/non-draft/clean PR, and the exact current head SHA (eval sessions cannot merge).
+- **`pr-review` ([operation guide](demos/pr-review/README.md)):** `council` and `leaving-pr-comments` with three reviewer subagents (`reviewer-a`, `reviewer-b`, `reviewer-c`). All three inherit the same parent model, outputting a Chinese `Council review` table and an explicit notice that the review uses three perspectives on one model rather than three separate model providers. Its root tools are read/search/delegate only, and its authored tools never post comments or edit PR descriptions.
+
+Both demos disable their GitHub channel until `bot/lib/settings.ts` replaces `"OWNER/REPO"`. Even after configuring a repository, automatic reply comments, reactions, and `@mention` triggers remain disabled. `pr-review` pre-fetches a bounded, revision-checked diff snapshot on the host side before the sandboxed model turn; direct `pr_wait` calls from inside a sandboxed model turn remain unverified.
+
+## Limitations and Verification Status
+
+The [independent evaluation](evaluation/README.md) covers the corrected converter and revised routing evals. Earlier demo model runs and the signed PR replay were recorded before the rename from `cc2agent`; their [original evidence](docs/evidence/online-2026-10-27.json) retains its source hashes. These are separate runs, with their respective scope preserved.
+
+- **Tool-name scan coverage:** a fixed, case-sensitive identifier list detects `WebFetch`, `WebSearch`, `AskUserQuestion`, `request_user_input`, `delegate_task`, `orchestrator_capabilities`, `watch_pull_request`, `unwatch_pull_request`, and `Monitor` in bodies and supporting Markdown. Matches may include instructions prohibiting a call; absence of a match does not establish compatibility. Source prompts are not rewritten.
+- **Root allowlists do not isolate subagents:** `--root-tools` restricts the root agent only. In `@grok/agent-sdk@0.3.0`, `task` subagents retain the harness `task` toolset. Never assume a root allowlist makes child agents read-only, and never treat `shell` as read-only (it can write files and run arbitrary commands).
+- **Script tools are disabled stubs:** conversion never executes source scripts. Generated `bot/tools/*.ts` wrappers return `AGENT2CURSOR_STUB_DISABLED` until an operator audits `.cursor/skills/<id>/scripts/*`, implements the JSON stdin/stdout contract, and enables `shell`.
+- **Scoped input/output guards:** conversion refuses to overwrite existing output directories, rejects symlinks, caps output at 128 MiB, skips or rejects known credential paths (`.env`, `.npmrc`, private key files), and rejects sensitive YAML/TOML keys (`token`, `apiKey`, `secret`). Parser diagnostics never echo source values. It does not scan arbitrary prose or binary attachments for secrets.
+
+**Verification summary (each evidence level is tracked separately):**
+
+| Evidence level | Status | What is and is not proven |
+| --- | --- | --- |
+| Offline tests & SDK structure | **PASS** (existing evidence) | 59 local tests passed before repository cleanup. Generated projects passed SDK `validate` / `info` / `eval --list` and strict `tsc`, with their own dependencies installed in independent temporary directories. `eval --list` proves case discovery only. Cleanup did not rerun these suites |
+| Independent conversion and routing evaluation | **PASS** (bounded dataset) | 24/24 normal conversions and post-install validations; revised generated routing evals passed 41/41 across 30 projects. Three real tasks, each repeated three times, matched direct-copy/plugin baselines. [Counts and source hashes](docs/evidence/independent-evaluation.json) |
+| Live model runs | **PASS** (narrow cases) | Official `agent-sdk login` succeeded. `migration-smoke` passed (**1 case / 2 assertions**: `succeeded`, `loadedSkill`). `pr-review` council inline diff passed (**1 case / 9 assertions**, same model / 3 perspectives). `full-send` local `run` loaded the skill with 1 read call and 0 writes/execs/merges |
+| GitHub PR replay | **PASS** (local replay) | [Private test PR #1](https://github.com/mreasonyang/agent2cursor/pull/1) passed via HMAC-signed **local replay** (bounded snapshot + 3 reviewer delegates + Chinese table; 0 tool errors, 0 writes/execs, 0 GitHub comments/reactions/reviews; PR closed unmerged). Not a live hosted webhook delivery |
+| Cloud hosting | **Not run / On hold** | `agent-sdk deploy --dry-run` stopped because the test account has no default team configured; no hosted deployment or URL exists |
+
+These checks do not prove average model quality, multi-provider routing, or child-agent tool isolation. Full records: [acceptance results](docs/acceptance.md) · [upstream verification](docs/upstream-verification.md) · [sanitized online evidence](docs/evidence/online-2026-10-27.json) · [official example provenance](docs/official-examples.provenance.json).
+
+## Contributing and License
+
+Maintainer commands (`npm run check`, `npm run test:sdk`, `node scripts/build-demos.mjs`) and safety invariants are in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+`agent2cursor` is MIT-licensed (`Copyright (c) 2026 Eason Yang`, [LICENSE](LICENSE)). The pinned snapshot in [`fixtures/tstack`](fixtures/tstack) ([`PROVENANCE.json`](fixtures/tstack/PROVENANCE.json)) and the adapted demos derive from [t3dotgg/tstack](https://github.com/t3dotgg/tstack), `Copyright (c) 2026 Theo Browne`, under the MIT license ([`fixtures/tstack/LICENSE`](fixtures/tstack/LICENSE) and `LICENSE-tstack`); recognized `tstack` inputs must retain this MIT notice. `@grok/agent-sdk@0.3.0` is a proprietary dependency (no SDK source or docs are vendored here). Not affiliated with or endorsed by Theo Browne, T3, Anthropic, Cursor, Anysphere, or xAI. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/README.zh-CN.md

@@ -0,0 +1,203 @@
+# agent2cursor
+
+把已写好的 Claude Code / Codex 子代理（subagents）与 Agent Skills 整理成可编辑的 [Cursor Agent SDK](https://cursor.com/docs/agent-sdk)（`@grok/agent-sdk`）TypeScript 项目，同时生成路由评测（eval）骨架和逐字段迁移报告。
+
+[English](README.md) · **0.1.0** · [MIT 许可证](LICENSE) · Node **>=22.13** · 适配 **`@grok/agent-sdk@0.3.0`**
+
+![将 Claude 子代理与 Skills 转换为 Agent SDK 项目并生成逐字段迁移报告](docs/assets/agent2cursor-demo.gif)
+
+如果你手里已经有写好的 `.claude/agents/*.md` 或 `.codex/agents/*.toml` 子代理，或存放在目录中的 `SKILL.md` 技能文件（包括 [t3dotgg/tstack](https://github.com/t3dotgg/tstack) 这类工作流），`agent2cursor` 可以把这些散装资产整理成独立的 Cursor Agent SDK 项目。它产出可编辑源码、逐字段去向报告和初始路由 eval——**不会**迁移底层模型本身或聊天历史，也**不会**自动保证运行时行为或子代理权限边界与源平台等价。
+
+```text
+.claude/agents/code-reviewer.md → bot/subagents/code-reviewer/{agent.ts,instructions.md}
+.codex/agents/reviewer.toml     → bot/subagents/<name>/{agent.ts,instructions.md}
+skills/<name>/SKILL.md          → bot/skills/<name>/SKILL.md
+skills/*/scripts/*              → bot/tools/*.ts（默认禁用的 JSON 适配存根）
+源配置字段 + 路由检查             → MIGRATION.zh-CN.md（或 .en.md）+ evals/*.eval.ts
+```
+
+## 快速试用
+
+npm 包名为 **`@kyun.si/agent2cursor`**，安装后的命令为 **`agent2cursor`**：
+
+```bash
+npx --yes @kyun.si/agent2cursor@0.1.0 --help
+npm install --global @kyun.si/agent2cursor@0.1.0
+agent2cursor inspect .claude/agents
+agent2cursor convert .claude/agents --out ./my-agent
+```
+
+只传机器上实际存在的路径。Codex 输入可以使用 `.codex/agents` 和 `.agents/skills`，也可混合 Claude 与 Codex 输入。转换在本地执行，不需要 Cursor 账号。
+
+若要试用仓库内置的 [`fixtures/`](fixtures/claude) 样本，请从源码目录编译：
+
+```bash
+npm ci --ignore-scripts
+npm run build
+
+# 预览或转换仓库自带的 Claude 子代理 + tstack full-send 技能闭包（默认生成中文报告）
+node dist/cli.js inspect ./fixtures/claude ./fixtures/tstack/skills/full-send --with-deps
+node dist/cli.js convert ./fixtures/claude ./fixtures/tstack/skills/full-send \
+  --with-deps --out /tmp/my-agent
+```
+
+```text
+⚠️ 子代理限制未生效（4 个）：源 tools / disallowedTools / permissionMode 未迁移。SDK 校验通过不代表只读；--root-tools 只设置根代理白名单。
+agent2cursor v0.1.0 → @grok/agent-sdk 0.3.0
+扫描: 4 agents, 5 skills, 1 script stubs
+...
+```
+
+在这组内置样本输入下（4 个子代理、5 个 skill 含 4 个 `tstack` 依赖、1 个脚本存根），`agent2cursor` 会生成 **28 个文件**，并在 `/tmp/my-agent/MIGRATION.zh-CN.md` 逐项记录迁移提醒。具体提醒数与 `自检`（`Validation`）状态会随输入资产、参数及已安装依赖而变化（在 `/tmp/my-agent` 安装依赖前显示 `dependencies-missing` 属正常现象）。
+
+保持当前仓库目录不变，直接为生成项目安装依赖并运行结构校验与 `doctor`：
+
+```bash
+(cd /tmp/my-agent && npm install && npx agent-sdk validate --dir . && npx agent-sdk eval --dir . --list)
+node dist/cli.js doctor --dir /tmp/my-agent
+```
+
+维护者用 `npm run pack:local` 构建公开归档，再用 `npm run publish:npm` 发布已经验证的同一归档；见 [CONTRIBUTING.md](CONTRIBUTING.md#npm-release)。源码工程保留 `private: true`，公开归档不包含这个字段。
+
+- **SDK 真实包名：** [Cursor Agent SDK 官方文档](https://cursor.com/docs/agent-sdk)指定的包名为 **`@grok/agent-sdk`**（旧称 `@cursor/bdk`），请勿使用早期公告中的 `@cursor/agent-sdk`；详见[上游核实说明](docs/upstream-verification.md)。生成的 `package.json` 将 `@grok/agent-sdk` 锁定为 `0.3.0`，并声明 `zod` 为 `^3.25.0`。
+- **不同步骤的账号与权限要求：**
+  1. **离线转换与结构校验**（`convert`、`inspect`、`doctor`、`agent-sdk validate`、`agent-sdk eval --list`）：无需登录 Cursor 账号或配置 API Key。
+  2. **调用真实模型运行**（`agent-sdk dev`、`agent-sdk run`、实际执行 `agent-sdk eval`）：需先运行 `agent-sdk login` 登录，且账号具备对应模型访问权限。
+  3. **云端托管部署**（`agent-sdk deploy`）：可选步骤，需账号所属团队已开通 hosting 权限并授权对应仓库。
+
+`convert` / `demo` 在工程已写出、但缺少声明的 SDK 或 `zod` 依赖时退出 0，`validation.status` 为 `dependencies-missing`，并列出缺失包名；这时尚未执行校验。安装依赖后运行 `agent2cursor doctor --dir <project>`，`doctor` 在校验通过前仍返回非零。真实校验错误仍使转换退出 1；转换器不会自动安装依赖。
+
+## 转换 Codex 资产
+
+完成本地构建后，可以传入项目或个人子代理目录、单个 TOML 文件，以及 skill 目录；也可以与 Claude 输入一起转换：
+
+```bash
+node dist/cli.js inspect .codex/agents .agents/skills
+node dist/cli.js convert .codex/agents .agents/skills --out ./my-codex-agent
+# 仓库内的合成示例，无需安装 Codex 或登录账号
+node dist/cli.js convert fixtures/codex/project --out /tmp/codex-example
+```
+
+只传实际存在的路径，子代理和 skill 可以单独转换。个人独立子代理目录 `~/.codex/agents` 也支持。传入项目根目录时会发现这些子代理树和 skill 目录，无关 TOML 文件不会被当作子代理。
+
+| Codex 输入 | 转换方式 |
+| --- | --- |
+| 独立 TOML 的 `name`、`description`、`developer_instructions` | 必须是非空字符串；分别生成子代理 ID、委派描述和解析后的指令文本。格式不合要求时明确报错。 |
+| `model` | 默认省略，继承目标父代理模型；支持 `--model-map 源ID=目标ID` 与 `--keep-model`，校验不证明模型可调用。 |
+| `model_reasoning_effort`、`model_reasoning_summary`、`model_verbosity` | 逐字段标为丢弃；模型 ID 映射不包含这些参数。 |
+| `features.*`、`skills.*` | 逐字段标为降级，子代理能力与 skill 限制未生效；不会读取其中引用的 skill 路径。 |
+| sandbox、approval、provider、MCP 等父会话配置 | 不导入；这些字段在 Codex 独立子代理中也不能覆盖父会话。需人工设置目标运行环境。 |
+| `agents/openai.yaml` | 文件原样保留；有效的 `interface.default_prompt` 用于 eval。UI、调用策略、工具依赖及未知字段逐项说明，调用限制不生效，MCP 不自动连接。 |
+
+当前支持的是 **Codex 独立 TOML 子代理 → Cursor Agent SDK**。不转换整个会话，也不输出 Codex 配置；父级 `config.toml`、`AGENTS.md`、凭证和旧式 `[agents.<name>] config_file` 声明不会导入。继承的指令、工具与 skills 需要另行审核。Codex 专用工具名会给出迁移提示，不自动改写原文。见 [Codex 样例](fixtures/codex) 与[核实范围](docs/upstream-verification.md#codex-input-adapter-2026-10-28)。
+
+## 适用场景与官方方案对比
+
+`@grok/agent-sdk` 已原生支持直接加载 `SKILL.md` 和挂载插件，可按手头资产选择最简方案：
+
+| 方案 | 适用情况 |
+| --- | --- |
+| 直接复制 `SKILL.md` | 只有现成兼容的 `SKILL.md` 目录，不需要转换子代理、脚本存根或生成逐字段迁移报告 |
+| SDK `cursorPlugin()` | 已有带清单（manifest）的 Cursor / Claude 插件，只需运行时挂载 |
+| `agent-sdk init --from automation:` / `migrate` | 从 Cursor Automation 迁移，或升级旧版 SDK 项目 |
+| **`agent2cursor`** | 手头有散装 Claude `.md` / Codex `.toml` 子代理、多技能目录或 `tstack` 工作流，希望导出为可编辑的 SDK 源码、获得逐字段损失清单、异构工具警告、禁用脚本存根与路由 eval 骨架 |
+
+## 转换前后实例与字段去向（`code-reviewer`）
+
+以仓库自带的 [`fixtures/claude/agents/code-reviewer.md`](fixtures/claude/agents/code-reviewer.md) 为例：
+
+```markdown
+---
+name: code-reviewer
+description: Review changed code for defects, maintainability, and missing verification.
+tools: Read, Grep, Glob
+model: sonnet
+---
+Review the changed code. Prioritize concrete defects and cite the affected file and line.
+Do not edit files. Explain what was verified and what remains uncertain.
+```
+
+`agent2cursor convert` 会生成 `bot/subagents/code-reviewer/agent.ts`，把提示词正文写入 `bot/subagents/code-reviewer/instructions.md`，并在 `MIGRATION.zh-CN.md`（或 `MIGRATION.en.md`）逐项记录每个 frontmatter 字段的结论：
+
+```ts
+// bot/subagents/code-reviewer/agent.ts
+// Generated by agent2cursor. Review the migration report before running.
+import { defineAgent } from "@grok/agent-sdk";
+
+export default defineAgent({
+  description: "Review changed code for defects, maintainability, and missing verification.",
+  // TODO(agent2cursor): tools: 危险：子代理工具限制未生效，task 子代理保留 harness 自己的工具集；不能假定根白名单会约束子代理。工具名参考映射 (read, grep, glob)；若必须强制只读，需使用独立代理或禁用 task，并另行约束执行环境；shell 可写入。
+  // TODO(agent2cursor): model: 已省略 model，继承父代理模型；使用 --model-map 显式指定目标模型。
+});
+```
+
+<details>
+<summary><strong>逐类输入与 frontmatter 字段去向表</strong></summary>
+
+| 源文件或字段 | SDK 输出位置 | 迁移结论 | 处理方式 |
+| --- | --- | --- | --- |
+| 子代理 `name` | `bot/subagents/<id>/` | `✅ 已映射` / `⚠️ 降级` | 已是合法目录 ID 时为 `✅`；发生字符规范化或缺失回退为文件名时为 `⚠️` |
+| 子代理 `description` | `bot/subagents/<id>/agent.ts` | `✅ 已映射` / `⚠️ 降级` | 非空有效时为 `✅`；缺失或空白时生成占位描述并标为 `⚠️` |
+| 子代理 Markdown 正文 | `bot/subagents/<id>/instructions.md` | `✅ 已映射` / `⚠️ 降级` | 正文未变化时标为已映射；追加共享技能预加载提示时明确标为降级，并说明保留原文、末尾追加提示 |
+| 子代理 `model` | `bot/subagents/<id>/agent.ts` | `✅ 已映射` / `⚠️ 降级` | `inherit` 直接省略（`✅`）；`sonnet`、`opus`、`haiku` 等默认省略以继承父模型（`⚠️`），除非用 `--model-map` 显式映射（`✅`）或用 `--keep-model` 原样保留（`⚠️`） |
+| 子代理 `tools` / `disallowedTools` | `MIGRATION.*.md` + `TODO(agent2cursor)` | `⚠️ 降级` | SDK `0.3.0` 不支持子代理级工具限制，`task` 子代理仍使用 harness `task` 工具集 |
+| 子代理 `skills` | `bot/instructions.md` + `instructions.md` | `⚠️ 降级` | 生成共享 skill 加载提示（无原生子代理独立预加载机制） |
+| `permissionMode`、`hooks`、`mcpServers`、`memory` 及未知代理字段 | `MIGRATION.*.md` + `TODO(agent2cursor)` | `❌ 丢弃` | 目标 SDK 无已核实的等价字段，在报告中列出供人工补齐 |
+| `SKILL.md` 及附属文件 | `bot/skills/<id>/**` | `✅ 已映射` / `⚠️ 降级` | 保留正文、附属文件与额外 frontmatter（`license`、`metadata.*`）；`name`/`description` 被规范化或缺失时标为 `⚠️`，`allowed-tools` 标为 `⚠️` |
+| `skills/*/agents/openai.yaml` | 原样元数据文件 + `evals/skills.eval.ts` | `✅ 已映射` / `⚠️ 降级` | 有效 `interface.default_prompt` 用作 eval 触发词；UI、调用策略、工具依赖及未知字段逐项报告，仅保留元数据不代表 SDK 支持其运行时语义 |
+| `skills/*/scripts/*` | `bot/skills/<id>/scripts/*` + `bot/tools/<script>.ts` | `⚠️ 降级` | 复制脚本内容（去除可执行位），并在 `bot/tools/` 生成默认禁用的 `execution: "agent"` 存根（`AGENT2CURSOR_STUB_DISABLED`） |
+
+</details>
+
+## 命令行参考
+
+| 命令或参数 | 说明 |
+| --- | --- |
+| `convert <input...>` | 将 Claude `.md` / Codex 独立 `.toml`、`.claude/agents/` / `.codex/agents/`、skill 目录或 `tstack` 仓库转换为新的 SDK 项目 |
+| `inspect <input...>` | 仅输出迁移报告（或 `--json` 摘要），不写入任何文件 |
+| `demo <full-send\|pr-review>` | 导出内置的两个 `tstack` 改编示例项目（支持 `--out <dir>`、`--json`、`--no-validate`） |
+| `doctor [--dir <project>]` | 检查 Node `>=22.13` 并调用 `agent-sdk validate` 输出脱敏诊断摘要 |
+| `--out <dir>` | `convert` 的新输出目录（默认 `./my-agent`；路径已存在时拒绝覆盖） |
+| `--name <name>` | 生成的代理名称（`1–64` 位小写字母、数字、`-` 或 `_`，以字母或数字开头，默认 `converted-agent`） |
+| `--lang <zh\|en>` | 生成的说明书、eval 提示词与 `MIGRATION.zh-CN.md` / `MIGRATION.en.md` 语言（默认 `zh`） |
+| `--with-deps` | 按 `tstack` 依赖图自动补齐同级目录中被依赖的关联技能 |
+| `--model-map <map>` | 显式映射模型 ID，如 `--model-map sonnet=<已核实模型ID>`（需用自己的账号核实可用性） |
+| `--keep-model` | 原样保留未验证的源模型 ID，而不是省略以继承父模型 |
+| `--root-tools <list>` | 显式设置根代理工具白名单（`read,grep,glob,ls,shell,edit,task,delete`）；不传则使用 SDK 默认值 |
+| `--dry-run` / `--no-validate` / `--json` | 仅计算生成计划不写文件 / 跳过 `agent-sdk validate` / 输出机器可读 JSON |
+
+## 内置示例（Demos）
+
+两个示例均基于 [t3dotgg/tstack](https://github.com/t3dotgg/tstack) 固定 MIT 快照（`7de017b3fc9d50c03cf3ecb98fb71e0ca65a78bd`）改编为中文工作流，附带 `LICENSE-tstack` 与 `TSTACK-PROVENANCE.json`。可通过 `node dist/cli.js demo <full-send|pr-review> --out <dir>` 导出：
+
+- **`full-send`（[操作说明](demos/full-send/README.md)）：** 含 5 个技能（`full-send`、`sol-loop`、`file-pr`、`babysit-pr`、`leaving-pr-comments`）、1 个 `reviewer` 子代理、做一次只读快照且不轮询的 `pr_wait` 工具、默认禁用的 `pr_wait_script` 存根（保留原版 Python `pr-wait` 供审阅），以及带门禁的 `merge_pr` 工具。根代理不含 `shell`，因此**默认只完成本地代码修改、评审并输出 PR 草稿，在发布和合并前停止**——未实现自动跑测试、`git push` 和创建 PR。`merge_pr` 默认关闭，必须同时满足 `AGENT2CURSOR_ALLOW_MERGE=1`、人工批准本次调用、匹配已配置 GitHub 仓库会话、PR 处于 open/非 draft/clean 状态且 `expectedHead` 精确匹配当前 head SHA（eval 会话禁止合并）。
+- **`pr-review`（[操作说明](demos/pr-review/README.md)）：** 含 `council` 与 `leaving-pr-comments` 技能及 3 个评审子代理（`reviewer-a`、`reviewer-b`、`reviewer-c`）。三个子代理继承同一父模型，输出中文 `Council review` 评分表，并明确声明当前是同一模型的三种视角而非三家模型厂商。根代理仅保留只读搜索与委派工具，不提供发评论或改 PR 描述的工具。
+
+两个示例在 `bot/lib/settings.ts` 保持默认 `"OWNER/REPO"` 时完全禁用 GitHub channel；配置实际仓库后也显式关闭自动回复评论、reaction 和 `@mention` 触发。`pr-review` 在服务端预先拉取并校验有界 diff 快照供沙箱内模型读取；而在沙箱模型回合中直接调用 `pr_wait` 仍未通过验收。
+
+## 核心限制与验收状态
+
+[独立评测](evaluation/README.md)覆盖修复后的转换器与新版路由 eval。较早的 demo 真实模型与 PR 签名回放结果来自更名之前（原名 `cc2agent`），[原始证据](docs/evidence/online-2026-10-27.json)保留对应源码哈希；不同轮次的结果与验证范围分别记录。
+
+- **工具名扫描范围：** 固定名单区分大小写检测正文和附属 Markdown 中的 `WebFetch`、`WebSearch`、`AskUserQuestion`、`request_user_input`、`delegate_task`、`orchestrator_capabilities`、`watch_pull_request`、`unwatch_pull_request`、`Monitor`。命中可能来自禁止调用的说明；未命中不代表工具兼容，不改写源提示词。
+- **根代理工具白名单不等于子代理隔离：** `--root-tools` 仅约束根代理。`@grok/agent-sdk@0.3.0` 的 `task` 子代理仍保有 harness 自身的 `task` 工具集，不能把根白名单当作子代理只读的证明；同时任何启用 `shell` 的配置都能写文件和执行任意命令，绝非只读。
+- **脚本工具默认是禁用存根：** 转换过程绝不执行输入脚本。生成的 `bot/tools/*.ts` 固定返回 `AGENT2CURSOR_STUB_DISABLED`，需操作员审查 `.cursor/skills/<id>/scripts/*` 中的原脚本、实现 JSON stdin/stdout 契约并开启 `shell` 后才能启用。
+- **输入与输出防护范围：** 转换器拒绝覆盖已有输出目录、拒绝符号链接、限制单次生成体积上限为 128 MiB，跳过或拒绝已知凭据路径（`.env`、`.npmrc`、私钥文件），并拒绝敏感 YAML/TOML 键名（`token`、`apiKey`、`secret`），解析错误不回显源值；它不会对任意正文段落或二进制附件做全量秘密扫描。
+
+**当前验收状态摘要（各证据层级严格区分）：**
+
+| 证据层级 | 状态 | 已验证范围与未覆盖边界 |
+| --- | --- | --- |
+| 离线单测与结构校验 | **PASS**（已有证据） | 仓库清理前 59 项本地测试通过。生成项目在独立临时目录中安装自身依赖，通过 SDK `validate` / `info` / `eval --list` 及严格 `tsc`。`eval --list` 仅证明发现用例；本次清理未重跑这些测试 |
+| 独立转换与路由评测 | **PASS**（限定数据集） | 正常转换及安装后校验 24/24；新版自动路由 eval 在 30 个项目中 41/41 通过。3 个真实任务各重复 3 次，与直接复制/插件对照打平。[计数与源码哈希](docs/evidence/independent-evaluation.json) |
+| 真实模型运行 | **PASS**（窄用例） | 已完成官方 `agent-sdk login`。`migration-smoke` 通过（**1 条用例 / 2 个断言**：`succeeded`、`loadedSkill`）；`pr-review` 内联 diff 评审通过（**1 条用例 / 9 个断言**，同模型 3 视角）；`full-send` 本地 `run` 完成 1 次 skill 读取，0 次写入/执行/合并 |
+| GitHub PR 回放 | **PASS**（本地回放） | [私有测试 PR #1](https://github.com/mreasonyang/agent2cursor/pull/1) 经 HMAC 签名**本地回放**通过（有界快照 + 3 次子代理委派 + 中文评分表；0 工具错误、0 写入/执行、0 GitHub 评论/reaction/review；测试 PR 已关闭且未合并）。不等于线上托管 webhook 投递 |
+| 云端托管 | **未运行 / 暂缓** | 测试账号未配置默认团队（`no default team`），`agent-sdk deploy --dry-run` 在前置条件处停止，未执行实际部署，无部署 URL |
+
+上述单点结果不证明任意输入下的平均模型质量、多厂商路由或子代理运行时隔离。完整记录见：[验收记录](docs/acceptance.md) · [上游核实说明](docs/upstream-verification.md) · [脱敏线上证据](docs/evidence/online-2026-10-27.json) · [官方示例来源记录](docs/official-examples.provenance.json)。
+
+## 开发维护与许可证
+
+维护者自检命令（`npm run check`、`npm run test:sdk`、`node scripts/build-demos.mjs`）与仓库安全守则见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+`agent2cursor` 采用 [MIT 许可证](LICENSE)（`Copyright (c) 2026 Eason Yang`）。[`fixtures/tstack`](fixtures/tstack)（[`PROVENANCE.json`](fixtures/tstack/PROVENANCE.json)）中的固定快照与两个改编示例源自 [t3dotgg/tstack](https://github.com/t3dotgg/tstack)，`Copyright (c) 2026 Theo Browne`，采用 MIT 许可（保存在 [`fixtures/tstack/LICENSE`](fixtures/tstack/LICENSE) 与 `LICENSE-tstack` 中）；被识别的 `tstack` 输入源必须保留该 MIT 声明。`@grok/agent-sdk@0.3.0` 是专有依赖（本仓库不内置或再分发其源码与文档）。本项目与 Theo Browne、T3、Anthropic、Cursor、Anysphere 或 xAI 无官方关联或背书。详见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,11 @@
+# Third-party notices
+
+agent2cursor's own implementation is MIT, Copyright (c) 2026 Eason Yang.
+
+`t3dotgg/tstack` is Copyright (c) 2026 Theo Browne, distributed under MIT. The complete unmodified license is preserved in `fixtures/tstack/LICENSE` and in each demo's `LICENSE-tstack`.
+
+The snapshot comes from [commit 7de017b3fc9d50c03cf3ecb98fb71e0ca65a78bd](https://github.com/t3dotgg/tstack/tree/7de017b3fc9d50c03cf3ecb98fb71e0ca65a78bd), verified on 2026-10-27. `fixtures/tstack/PROVENANCE.json` records SHA-256 for every upstream file. Fixtures retain the original nine skills, README and license unchanged. Demo skills are Chinese adaptations: they use Agent SDK delegates, bounded read tools, honest same-model fallback, and stop before publication/merge by default. Every adapted SKILL.md identifies its upstream source and changes. The included `pr-wait` Python script is unchanged; execution is disabled by default.
+
+agent2cursor is not affiliated with or endorsed by Theo Browne, T3, Anthropic, Cursor, Anysphere or xAI.
+
+`@grok/agent-sdk@0.3.0` is a proprietary dependency, subject to its package license and Cursor's applicable terms. SDK source and bundled documentation are not redistributed in agent2cursor. Generated projects reference the package through npm and pin its version. Read its current license before use.

package/demos/full-send/LICENSE-tstack

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Theo Browne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.