feat(release): 1.0.0-rc.0 — API reports in CI, upgrade guide, version

[LinuxDevil]

Closes #245

What this does

Freezes the public surface for 1.0 as a release candidate:

• API reports: @microsoft/api-extractor (devDependency, 7.59.3) + scripts/api-report.ts. The script reads package.json exports and runs api-extractor programmatically (ExtractorConfig.prepare / Extractor.invoke) on each entry's types file, writing api/<subpath>.api.md — 20 reports for the 20 current entries. api:update / api:check scripts added; api/ is not in files.
• Which mechanism: the real api-extractor, not the TypeScript-checker fallback. It followed tsup's chunked .d.ts declarations fine once compiler.overrideTsconfig was set to { moduleResolution: "bundler", module: "esnext", skipLibCheck: true, files: [<entry d.ts>] } (the .js-suffixed hashed chunk imports resolve under bundler resolution).
• ae-missing-release-tag is suppressed; ae-forgotten-export is written into the reports so unexported types used by public signatures stay visible. Reports are newlineKind: 'lf', contain no absolute paths, and .gitattributes pins api/** text eol=lf.
• CI: npm run api:check added to .github/workflows/ci.yml right after npm run build, in the main ci job only (the peers matrix installs different ai/zod pairings; the report reflects the default peers).
• CONTRIBUTING.md: new "Public API changes" paragraph — run npm run api:update, commit the report; reviewers read the diff.
• Version: 1.0.0-rc.0 in package.json, src/index.ts VERSION, packages/create-lousho-agent's dependency range (^1.0.0-rc.0; its own version stays 0.1.1), and package-lock.json. New src/version.test.ts pins VERSION to package.json version — worth having: alpha.9 shipped with VERSION still reading 1.0.0-alpha.8.
• docs/upgrading.md "Upgrading to 1.0", the seven sections in spec order: who needs it, import-move table (A1+A3, incl. the removed /core subpath), removed APIs and replacements (A2a/A2b/A2c), renamed APIs (A5 patch guardrails → patch checks), deprecated-but-working names through 1.x (three trigger adapters + ToolRunContext, RunUsage.promptTokens/completionTokens, AiSdkProvider.convertMessages), every behavior-changing ### Breaking/### Changed entry from the changelog with doc links, and what 1.0 promises (semver over exports + the api/ reports; deep dist//src/ imports internal). Linked from the README docs table and docs/installation.md. llms.txt/llms-full.txt regenerated.
• CHANGELOG: ## [Unreleased] split — a fresh empty ## [Unreleased] above ## [1.0.0-rc.0] - 2026-10-04 (today's date; the owner question in the issue is unanswered — happy to redate), with a link to the upgrade guide at the top of the entry.
• scripts/pack-smoke.ts thresholds comment updated with the measured sizes.

api:check catches a signature change (demo)

Renamed isValidEmail(email: ...)'s parameter locally, rebuilt, and npm run api:check failed with:

diff --git a/api/utils.api.md b/api/utils.api.md
@@ -492,7 +492,7 @@ export interface IStorageService {

 // @public
-export function isValidEmail(email: string): boolean;
+export function isValidEmail(address: string): boolean;

api-report: 1 entry failed:
  - utils: api/utils.api.md is out of date - run `npm run api:update` and commit the diff

Change reverted; api:check is green on this branch.

Live smoke run — blocked by an expired key, artifact otherwise verified ($0 spent)

The OpenRouter key in .claude/round3.env (and the round2.env one the ticket names) returns 401 "API key expired" on GET /api/v1/auth/key, so data.usage / data.limit_remaining could not be read and no real-model turn was run — the spend is $0. What did run on lousho-build-ai-agent-1.0.0-rc.0.tgz in a fresh temp project (ai@7, @ai-sdk/openai@4, zod, no optional peers):

• ESM import and CJS require of every no-optional-peer subpath — ./executor (7), ./flows (13), ./integrations (11), ./utils (16), ./tools (44), ./testing (5), ./hooks (1), ./triggers (11), ./mcp (7): all resolve and export.
• npm run pack-smoke: 948 entries / ~16.4 MiB unpacked / ~4.3 MiB packed, all checks pass (publish dry-run, 20/20 entries ESM+CJS, createAgent + mockModel turn, lousho --help, lousho doctor, tsc under bundler and node16).
• Every quick-start flow executed against the packed tarball on the mock provider: hello, a tool call, stream() deltas, a two-turn session, an approval resolved in code (awaiting-approval → Sent.), and the coding-agent pattern (createFsTools + createShellTool + NodeWorkspace) reading a file in a scratch dir.
• One real-model attempt for the record: the request reached OpenRouter and failed 401 API key expired — the SDK side behaved correctly (LOUSHO_PROVIDER_REQUEST_FAILED with statusCode: 401).
• registry-smoke does not support a local tarball (--version only), so step 3 of the live test does not apply. No cassette recorded.

A fresh OpenRouter key is needed to complete the one real-model turn; rerunning node live.mjs-equivalent costs well under the $0.50 budget (gpt-4o-mini, maxSteps ≤ 5).

Verification

Check	Result
npm run build	✅ (needs NODE_OPTIONS=--max-old-space-size=6144 for the DTS pass)
npm run api:check	✅ 20/20 reports up to date
npx vitest run	✅ 4381 passed, 8 skipped
npm run typecheck / lint / test:types	✅
npm run typecheck:tests	⚠️ 135 errors — identical count on main (A6b follow-up; not in CI), none from this change
npm run docs:verify-snippets -- --skip-build	✅ 260 snippets
npm run docs:llms:check	✅ regenerated files committed
npm run pack-smoke	✅ (with the DTS heap flag, as in CI)
Agent Forge: typecheck, typecheck:server, test, test:server	✅ 119 + 133 tests
src/version.test.ts	✅

Notes / owner questions

• I proceeded without the pre-start owner answers: date 2026-10-04 on the rc entry, version 1.0.0-rc.0 (alpha.9 had already shipped), the listed @deprecated names kept through 1.x (already decided in the ticket), create-lousho-agent version unchanged.
• Docs-site work is out of scope per the ticket; tracking issue opened: Docs site: add Upgrading to 1.0 page (nav + Arabic) agent-sdk-docs#12 (PAGES entry, docs.json nav in English and ar/, Arabic translation).
• No API changes were made beyond what the reports record; the report diffs are the new baseline.