feat(sdk-ts): automate semantic-release for npm publishing (#52)

## Summary
- Migrates TypeScript SDK release automation to `semantic-release` using
the existing workflow file.
- Keeps TS SDK versioning independent from monorepo/Python release tags.
- Enforces commit-prefix-driven bumping for `sdk-ts` scope.
- Adds TS release runbook/policy docs and changelog file.

## Scope
- User-facing/API changes:
  - TS npm package release process is now semantic-release-driven.
  - TS release tags use `ts-sdk-vX.Y.Z`.
- Internal changes:
  - Updated existing workflow: `.github/workflows/release-sdk-ts.yml`.
  - Added `sdks/typescript/release.config.cjs`.
- Added semantic-release scripts/deps in `sdks/typescript/package.json`
and lockfile updates.
  - Added `sdks/typescript/CHANGELOG.md`.
  - Added `sdk-ts` scope in PR title validator.
- Out of scope:
  - Python semantic-release changes.
  - Server/OpenAPI architecture changes.

## Risk and Rollout
- Risk level: medium
- Rollout plan:
  - Merge this PR to `main`.
- Run `Release TypeScript SDK` workflow once with `dry_run=true` on
`main`.
  - Run again with `dry_run=false` on `main` to publish.
- Rollback plan:
  - Revert this PR and re-run existing manual publish path.

## Publishing 0.2.0 Test Status
- New workflow validated successfully on branch in both modes:
- dry run:
https://github.com/agentcontrol/agent-control/actions/runs/22649229718
- publish-mode dispatch:
https://github.com/agentcontrol/agent-control/actions/runs/22649269871
- `semantic-release` correctly skipped publish on branch `lev/ts-semver`
because release branch is `main`.
- Actual `0.2.0` publish test must be run from `main` after merge.

## Testing
- [ ] Added or updated automated tests
- [ ] Ran `make check` (or explained why not)
- [x] Manually verified behavior

Notes:
- Did not add new test files; this change is workflow/config/docs
focused.
- Ran `make sdk-ts-release-check` locally.
- Ran workflow dry-run and publish-mode dispatch on PR branch to
validate execution path.

## Checklist
- [x] Linked issue/spec (if applicable)
- [x] Updated docs/examples for user-facing changes
- [x] Included any required follow-up tasks

Links:
- Parent story:
https://app.shortcut.com/galileo/story/55974/define-typescript-sdk-semver-policy-and-release-alignment
- Implementation subtask:
https://app.shortcut.com/galileo/story/57429/implement-independent-commitdriven-semanticrelease-for-typescript-sdk

Author: lan17

.github/workflows/pr-title.yaml

@@ -29,6 +29,7 @@ jobs:
             chore
           scopes: |
             sdk
+            sdk-ts
             server
             models
             engine

.github/workflows/release-sdk-ts.yml

@@ -1,10 +1,12 @@
 name: Release TypeScript SDK
 
 on:
+  push:
+    branches: [ main ]
   workflow_dispatch:
     inputs:
       dry_run:
-        description: Run npm publish in dry-run mode
+        description: Run semantic-release in dry-run mode
         required: true
         type: boolean
         default: true
@@ -13,14 +15,20 @@ jobs:
   release-sdk-ts:
     runs-on: ubuntu-latest
     permissions:
-      contents: read
+      contents: write
       id-token: write
+      issues: write
+      pull-requests: write
     env:
       SPEAKEASY_API_KEY: ${{ secrets.SPEAKEASY_API_KEY }}
+      NPM_CONFIG_PROVENANCE: "true"
 
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GALILEO_AUTOMATION_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
 
       - name: Setup Python
         uses: actions/setup-python@v5
@@ -36,7 +44,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: "20"
+          node-version: "22.14.0"
           registry-url: "https://registry.npmjs.org"
 
       - name: Install pnpm
@@ -66,24 +74,23 @@ jobs:
       - name: Build TypeScript SDK
         run: make sdk-ts-build
 
-      - name: Publish TypeScript SDK (dry run)
-        if: ${{ inputs.dry_run }}
+      - name: Run semantic-release
         working-directory: ./sdks/typescript
-        run: npm publish --dry-run
-
-      - name: Ensure npm token exists
-        if: ${{ !inputs.dry_run }}
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GALILEO_AUTOMATION_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
-          if [[ -z "${NODE_AUTH_TOKEN}" ]]; then
+          set -euo pipefail
+
+          if [[ "${{ github.event_name }}" == "workflow_dispatch" && "${{ inputs.dry_run }}" == "true" ]]; then
+            echo "Running semantic-release dry-run."
+            pnpm run release:dry-run
+            exit 0
+          fi
+
+          if [[ -z "${NPM_TOKEN}" ]]; then
             echo "NPM_TOKEN secret is required for publish runs."
             exit 1
           fi
 
-      - name: Publish TypeScript SDK
-        if: ${{ !inputs.dry_run }}
-        working-directory: ./sdks/typescript
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: npm publish --provenance
+          pnpm run release

sdks/typescript/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+
+All notable changes to the TypeScript SDK are documented in this file.

sdks/typescript/README.md

@@ -143,3 +143,22 @@ Release:
 
 - Package name: `agent-control`
 - Release runbook: `RELEASING.md`
+
+## Semantic Versioning
+
+TypeScript SDK versioning is independent from server/monorepo tags and is automated with `semantic-release`.
+
+Release-triggering commit prefixes for scope `sdk-ts`:
+
+- `feat(sdk-ts): ...` -> minor bump
+- `fix(sdk-ts): ...` -> patch bump
+- `perf(sdk-ts): ...` -> patch bump
+- `refactor(sdk-ts): ...` -> patch bump
+- `chore(sdk-ts): ...` -> patch bump
+- `BREAKING CHANGE` footer or `!` -> major bump
+
+To preview the next computed release locally:
+
+```bash
+pnpm run release:dry-run
+```

sdks/typescript/RELEASING.md

@@ -2,13 +2,24 @@
 
 This package publishes to npm as `agent-control`.
 
+## Release policy
+
+- TypeScript SDK releases are independent from server/monorepo version tags.
+- Releases are commit-driven via `semantic-release`.
+- Expected release-triggering commit scopes use `sdk-ts`:
+  - `feat(sdk-ts): ...` -> minor bump
+  - `fix(sdk-ts): ...`, `perf(sdk-ts): ...`, `refactor(sdk-ts): ...`, `chore(sdk-ts): ...` -> patch bump
+  - `BREAKING CHANGE` or `!` -> major bump
+
 ## One-time setup
 
 1. Ensure npm ownership for `agent-control` is configured.
 2. Add repository secret `NPM_TOKEN` with publish permission.
-3. Ensure GitHub Actions has `id-token: write` permission for provenance.
+3. Ensure workflow `.github/workflows/release-sdk-ts.yml` has:
+   - `contents: write` for release commit/tag
+   - `id-token: write` for npm provenance
 
-## Pre-release checklist
+## Pre-release checks
 
 Run from repo root:
 
@@ -21,36 +32,34 @@ This validates:
 - Generated client is current
 - Lint, typecheck, test, and build all pass
 
-## Local package dry run
+## Local semantic-release preview
 
-Run from repo root:
+Run from `sdks/typescript`:
 
 ```bash
-make sdk-ts-publish-dry-run
+pnpm run release:dry-run
 ```
 
-This runs the publish gate checks and then executes `npm publish --dry-run`.
+This previews the next semantic version and release notes without publishing.
 
 ## GitHub Actions release flow
 
-Use workflow `.github/workflows/release-sdk-ts.yml`:
+Workflow: `.github/workflows/release-sdk-ts.yml`
 
-1. Trigger manually with `dry_run=true` first.
-2. Confirm all checks and packaging output are correct.
-3. Trigger again with `dry_run=false` to publish.
+- Automatic publish: runs on `push` to `main`.
+- Manual preview: `workflow_dispatch` with `dry_run=true`.
+- Manual publish: `workflow_dispatch` with `dry_run=false`.
 
-The publish run performs:
-- `make sdk-ts-generate-check` (this generates OpenAPI from server code, then checks SDK/overlay drift)
-- `make sdk-ts-lint`
-- `make sdk-ts-typecheck`
-- `make sdk-ts-test`
-- `make sdk-ts-build`
-- `npm publish --provenance`
+Release job performs:
+- `make sdk-ts-release-check`
+- `semantic-release` (updates `package.json` + `CHANGELOG.md`, creates Git tag/release, publishes to npm)
 
 ## Post-publish verification
 
-1. Install from npm in a clean temp project:
+1. Confirm npm version/dist-tag:
+   - `npm view agent-control version dist-tags --json`
+2. Install from npm in a clean temp project:
    - `npm i agent-control`
-2. Confirm import works:
+3. Confirm import works:
    - `import { AgentControlClient } from "agent-control";`
-3. Verify package metadata on npm and GitHub release notes.
+4. Verify GitHub release/tag and changelog update.

sdks/typescript/package.json

@@ -49,7 +49,9 @@
     "test:watch": "vitest",
     "generate": "make generate",
     "generate:check": "make generate-check",
-    "speakeasy:install": "make speakeasy-install"
+    "speakeasy:install": "make speakeasy-install",
+    "release": "semantic-release",
+    "release:dry-run": "semantic-release --dry-run"
   },
   "dependencies": {
     "zod": "^4.1.11"
@@ -58,7 +60,14 @@
     "@types/node": "^22.14.1",
     "@typescript-eslint/eslint-plugin": "^8.30.1",
     "@typescript-eslint/parser": "^8.30.1",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.6",
+    "@semantic-release/npm": "^12.0.2",
+    "@semantic-release/release-notes-generator": "^14.1.0",
     "eslint": "^8.57.1",
+    "semantic-release": "^25.0.2",
     "tsup": "^8.3.6",
     "typescript": "^5.8.2",
     "vitest": "^3.0.9"