[A7] Prepare the 1.0.0 release candidate: API report in CI, upgrade guide, version

[LinuxDevil]

Goal

After the wave-4 moves and removals, freeze the public surface for 1.0: a checked-in API report per entry point that CI compares on every pull request (so any change to the public API is visible and deliberate), an upgrade guide from 1.0.0-alpha.8 to 1.0, the version set to the release candidate, and one smoke run of the packed tarball against a real model. Publishing stays with the owner. Plan row A7; the root has 705 exports on cc5ddb8 and nothing records the surface today.

Current state

Verified on main at cc5ddb8:

• Version 1.0.0-alpha.8 in package.json:3 and src/index.ts:9 (export const VERSION = '1.0.0-alpha.8'); packages/create-lousho-agent/package.json:3 is 0.1.0 and depends on "@lousho/build-ai-agent": "^1.0.0-alpha.8" (:33). Tests pin the version string: src/cli/init/sdkDependency.test.ts:20, src/cli/init/templates.test.ts:5,13,51, src/cli/init.test.ts:29,98 (they pass a version in, so they do not need to change). scripts/pack-smoke.ts:37 comment names alpha.8 for its size thresholds. Nothing checks that VERSION equals package.json version.
• No API report: @microsoft/api-extractor is not a dependency; typedoc.json documents src/index.ts only. package.json exports has 14 entries today (A1 adds ./integrations, ./utils; A3 adds ./executor and removes ./core).
• Declarations: tsup with dts: true, splitting: true writes dist/<entry>.d.ts that import hashed chunks (dist/agent-BWzkJMtI.d.ts, dist/tool-CyJRDJEL.d.ts, ...).
• No release workflow: .github/workflows/ has ci.yml and e2e-studio.yml; publishing is manual (prepublishOnly: npm run build && npm run build:studio).
• CHANGELOG.md:8 ## [Unreleased] - 2026-09-28 collects everything since ## [1.0.0-alpha.8] - 2025-10-05 (:184).
• @deprecated names that will still exist after wave 4 (grep @deprecated in non-test src/ on cc5ddb8, minus what A2a/A2b remove): ToolRunContext (src/execution/toolRunContext.ts:15), RunUsage.promptTokens / completionTokens (src/models/usage.ts:81,83), AiSdkProvider.convertMessages (src/providers/aiSdkProvider.ts:260), and the three trigger adapters A4 deprecates.

Scope

In:

• API report: add @microsoft/api-extractor as a devDependency and scripts/api-report.ts, which reads package.json exports and, for each entry, runs api-extractor programmatically (ExtractorConfig.prepare({ configObject, packageJsonFullPath }), Extractor.invoke) on its types file, writing api/<name>.api.md named after the subpath, not the dist file (index.api.md for ., executor.api.md for ./executor, mcp.api.md for ./mcp, and so on). Release-tag messages (ae-missing-release-tag) are suppressed; ae-forgotten-export goes into the report so unexported types that public signatures use are visible. Scripts: "api:update": "tsx scripts/api-report.ts" (writes the reports) and "api:check": "tsx scripts/api-report.ts --check" (fails with the diff when a report differs). Both need npm run build first. The api/ folder is not added to files.
• If api-extractor cannot follow tsup's chunked declarations after configuring compiler.overrideTsconfig (moduleResolution: "bundler"), use the fallback, decided here so the ticket does not stall: scripts/api-report.ts writes api/<name>.api.txt with the TypeScript checker (every export of the entry's types file, sorted, with checker.typeToString of its declared type or the class / interface members), and api:check compares those. Say in the pull request which one you used and why.
• CI: in .github/workflows/ci.yml, after npm run build, add - run: npm run api:check.
• CONTRIBUTING.md: a short "Public API changes" paragraph: run npm run api:update and commit the report; a reviewer reads the report diff.
• Version: package.json version and src/index.ts VERSION become 1.0.0-rc.0; packages/create-lousho-agent/package.json depends on ^1.0.0-rc.0 (its own version stays 0.1.0 unless the owner says otherwise); package-lock.json updated with npm install. Add src/version.test.ts: VERSION equals package.json version. Update the comment at scripts/pack-smoke.ts:37 with the new measured sizes.
• Upgrade guide: new page docs/upgrading.md, "Upgrading to 1.0", sections in this order: (1) Who needs this page (anyone on 1.0.0-alpha.8 or an earlier alpha); (2) Import paths that moved (one table: name, old import, new import; from A1 and A3); (3) Removed APIs and their replacements (A2a, A2b, A2c); (4) Renamed APIs (A5's table); (5) Deprecated, still working in 1.x (A4's adapters and the four names listed under Current state, each with its replacement); (6) Other behavior changes since alpha.8 (collect every ### Breaking and ### Changed entry of CHANGELOG.md ## [Unreleased] that changes behavior, one line each with a link to its doc page); (7) What 1.0 promises (semver: every exports entry and the names in api/ are public; anything else, including deep imports of dist/ or src/, is internal). Link it from README.md's docs table and from docs/installation.md (one sentence; no new heading there).
• CHANGELOG: rename ## [Unreleased] - 2026-09-28 to ## [1.0.0-rc.0] - <date the owner gives> and add a fresh empty ## [Unreleased] above it; at the top of the rc entry, one line linking docs/upgrading.md.
• Decided: the deprecated names listed above are kept through 1.x and removed in 2.0, because removing them now needs separate breaking tickets and they cost nothing at runtime. The owner can overrule this in the issue before work starts.

Out:

• Publishing to npm, tagging a release, or creating a GitHub release: the owner does that after merging.
• Any further API change found while writing the report: open an issue per finding; do not change the API in this ticket.
• The docs site: a new page needs an entry in PAGES in scripts/sync-sdk-docs.mjs, navigation entries in docs.json (English and ar/) and an Arabic translation in LinuxDevil/agent-sdk-docs. Open an issue there and link it from the pull request.

Acceptance criteria

• api/ holds one report per exports entry; npm run api:check passes on the branch and fails when a public signature changes (show this once in the pull request by changing a parameter name locally and pasting the failure).
• ci.yml runs npm run api:check after the build.
• package.json, src/index.ts, packages/create-lousho-agent/package.json and package-lock.json say 1.0.0-rc.0; src/version.test.ts passes.
• docs/upgrading.md has the seven sections, every snippet passes npm run docs:verify-snippets -- --skip-build, and every moved, removed or renamed name from A1, A2a, A2b, A2c, A3 and A5 appears in it (check against their CHANGELOG entries).
• CHANGELOG has ## [1.0.0-rc.0] and an empty ## [Unreleased]; npm run docs:llms re-run.
• The live smoke run below passed, with its output summarized and the spend reported in the pull request.
• Full verification list in BRIEF-2.md passes, including npm run pack-smoke and the four Agent Forge checks.

Live test

Budget: at most 0.50 USD for this ticket (the wave-4 line in PLAN-2.md). Model: openai/gpt-4o-mini through OpenRouter (model: 'openrouter/openai/gpt-4o-mini', key from E:\agent-sdk\.claude\round2.env as in BRIEF-2.md). Read data.usage and data.limit_remaining before and after; if limit_remaining is under 1.00, do not run it and report that.

1. npm pack the release candidate and install the tarball in a fresh temp project outside the repository with ai@^7, @ai-sdk/openai@^4, zod.
2. Run, once each, with maxSteps at most 5 and short prompts: the quick start from docs/quick-start.md (hello, a tool call, streaming, a session with two turns, an approval resolved in code); the coding agent from G3's page against a scratch directory with one file; one import from every subpath that needs no optional peer (./executor, ./flows, ./integrations, ./utils, ./tools, ./testing, ./hooks, ./triggers, ./mcp) to prove they resolve in ESM and CJS.
3. If R1's registry-smoke script supports a local tarball, run it too and include its output.
   No cassette is recorded: this is a one-time release gate on the packed artifact, and the quick start and coding agent already have cassettes from G1 and G3. If the run finds a bug, open an issue; its fix ticket records its own cassette.

Dependencies

• All of A1, A2a, A2b, A2c, A3, A4, A5, A6a, A6b must merge first, and every wave-2 and wave-3 ticket the owner wants in 1.0 (the API report freezes what exists at that moment).
• G3 (the coding-agent page used by the smoke run) and R1 (registry smoke) should have merged.
• Owner decisions required before starting (see Notes).

Notes for the implementer

• Owner questions (record the answers in the issue before starting): (1) "Which date goes on ## [1.0.0-rc.0], and is 1.0.0-rc.0 the version string?" (2) "Keep the remaining deprecated names (ToolRunContext, RunUsage.promptTokens / completionTokens, AiSdkProvider.convertMessages, the three trigger adapters) through 1.x, as this ticket decides, or remove them before 1.0 in separate tickets?" (3) "Should create-lousho-agent also get a new version for the release?"
• api-extractor resolves ./chunk.js imports in .d.ts files only with a bundler or node16 resolution; the default config uses the package's tsconfig.json, whose include is src/**. Pass compiler.overrideTsconfig with { compilerOptions: { moduleResolution: "bundler", module: "esnext", skipLibCheck: true }, files: [<entry d.ts>] }.
• Reports must be stable across machines: no absolute paths, LF line endings (the repository has no .gitattributes on cc5ddb8; create one with the single line api/** text eol=lf).
• The typecheck-ai7 and typecheck-zod4 CI jobs build against different peer versions; run api:check only in the main job, so the report reflects the default peers.

---

Round 2 ticket A7. Before starting, read the agent brief (worktree rules, verification list, live-test budget) and the plan. One ticket is one pull request; put Closes #<this issue> in it.