refactor!: MCP-only toolset — every tool over tools/call, with search/execute sessions and submitFeedback()

.env.example

@@ -1,8 +1,11 @@
 # Required for all examples
 STACKONE_API_KEY=your-stackone-api-key
+
+# Optional: the examples read this and pass it as accountId (the SDK itself never reads it).
+# Without it, the SDK uses every active account linked to the API key
 STACKONE_ACCOUNT_ID=your-account-id
 
-# Required for OpenAI examples (openai-integration, openai-responses-integration, search-tools)
+# Required for OpenAI examples (openai-integration, openai-responses-integration, ai-sdk-integration)
 OPENAI_API_KEY=your-openai-api-key
 
 # Required for Anthropic examples (anthropic-integration, claude-agent-sdk-integration)

.github/workflows/check-title.yaml

@@ -7,6 +7,7 @@ on:
       - reopened
       - edited
       - synchronize
+      - ready_for_review
 
 permissions:
   pull-requests: read

.github/workflows/ci.yaml

@@ -116,6 +116,136 @@ jobs:
       - name: Run Tests
         run: pnpm exec vitest run --project root
 
+  # Enforces the wire contract shared with the Python SDK (StackOneHQ/sdk-conformance).
+  # StackOneHQ/sdk-conformance is private and requires CONFORMANCE_REPO_TOKEN.
+  # Fork PRs and Dependabot runs cannot access this secret and skip this gate;
+  # internal branches and PRs require the secret and fail if it is absent or expired.
+  check-secret:
+    runs-on: ubuntu-latest
+    outputs:
+      can-skip: ${{ steps.check.outputs.can-skip }}
+    steps:
+      - id: check
+        env:
+          TOKEN: ${{ secrets.CONFORMANCE_REPO_TOKEN }}
+          IS_FORK: ${{ github.event.pull_request.head.repo.fork == true }}
+          IS_DEPENDABOT: ${{ github.actor == 'dependabot[bot]' }}
+        run: |
+          if [ -z "$TOKEN" ] && { [ "$IS_FORK" = "true" ] || [ "$IS_DEPENDABOT" = "true" ]; }; then
+            echo "can-skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "can-skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  # Runs the full suite, both SDKs side by side, so a change here that the Python SDK does not
+  # match fails here rather than drifting.
+  conformance:
+    needs: check-secret
+    if: needs.check-secret.outputs.can-skip != 'true'
+    runs-on: ubuntu-latest
+    env:
+      # Pinned to a commit rather than the branch while StackOneHQ/stackone-ai-python#210 is
+      # open, so this only moves when we bump it deliberately. Switch to a main commit once it
+      # merges.
+      PYTHON_SDK_REF: 7e9b3efd1101eb953813486b789c57bd0645ad0e
+    steps:
+      - name: Check conformance token is configured
+        env:
+          TOKEN: ${{ secrets.CONFORMANCE_REPO_TOKEN }}
+        run: |
+          if [ -z "$TOKEN" ]; then
+            echo "::error::CONFORMANCE_REPO_TOKEN is not set or has expired."
+            exit 1
+          fi
+
+      - name: Checkout SDK
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          path: sdk
+
+      - name: Checkout conformance suite
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          repository: StackOneHQ/sdk-conformance
+          ref: 88c9400516f9842ca81dccce747f5d3e66e1fb0a
+          token: ${{ secrets.CONFORMANCE_REPO_TOKEN }}
+          path: sdk-conformance
+          persist-credentials: false
+
+      # Public, so no token.
+      - name: Checkout Python SDK
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          repository: StackOneHQ/stackone-ai-python
+          ref: ${{ env.PYTHON_SDK_REF }}
+          path: stackone-ai-python
+          persist-credentials: false
+
+      # tests/vectors is a copy of the suite's vectors/ (scripts/sync-vectors.sh), which the unit
+      # tests run. An edit to the copy, or a pin moved without a re-copy, fails here.
+      - name: Vendored vectors match the pinned sdk-conformance
+        run: diff -r sdk/tests/vectors sdk-conformance/vectors
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+        with:
+          version: 10.26.0
+          package_json_file: sdk-conformance/package.json
+
+      # 24, not 22: the SDK's devEngines pins Node ^24.11.0, and the suite runs on it too.
+      - name: Setup Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+
+      - name: Install SDK dependencies
+        working-directory: sdk
+        run: pnpm install --frozen-lockfile
+
+      # The runner imports the built dist, not src, so the harness grades the
+      # publishable artifact. It refuses a dist older than src.
+      - name: Build SDK
+        working-directory: sdk
+        run: pnpm run build
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          python-version: '3.13'
+
+      - name: Install Python SDK dependencies
+        working-directory: stackone-ai-python
+        run: uv sync --all-extras --locked
+
+      - name: Install conformance dependencies
+        working-directory: sdk-conformance
+        run: pnpm install --frozen-lockfile
+
+      - name: Run conformance suite
+        working-directory: sdk-conformance
+        env:
+          NODE_SDK_DIST: ${{ github.workspace }}/sdk/dist/index.mjs
+          PYTHON_SDK_DIR: ${{ github.workspace }}/stackone-ai-python
+        run: pnpm test -- --strict-schema
+
+  # Make this the one required status check. Individually required checks go
+  # missing when a job is renamed or a matrix entry is added, and nothing notices.
+  ci-ok:
+    if: always()
+    needs: [check-secret, gitleaks, lint, build-and-test, ai-peer-range, conformance]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require every job to have passed
+        run: |
+          if [ "${{ needs.gitleaks.result != 'success' || needs.lint.result != 'success' || needs.build-and-test.result != 'success' || needs.ai-peer-range.result != 'success' }}" = "true" ]; then
+            echo "::error::A required job did not pass (gitleaks: ${{ needs.gitleaks.result }}, lint: ${{ needs.lint.result }}, build-and-test: ${{ needs.build-and-test.result }}, ai-peer-range: ${{ needs.ai-peer-range.result }})"
+            exit 1
+          fi
+          if [ "${{ needs.conformance.result != 'success' && needs.check-secret.outputs.can-skip != 'true' }}" = "true" ]; then
+            echo "::error::Conformance check did not pass (result: ${{ needs.conformance.result }})"
+            exit 1
+          fi
+
   coverage:
     runs-on: ubuntu-latest
     if: github.ref == 'refs/heads/main'

.oxfmtrc.jsonc

@@ -3,5 +3,6 @@
 	"useTabs": true,
 	"semi": true,
 	"singleQuote": true,
-	"ignorePatterns": [".claude/settings.local.json", "CHANGELOG.md"],
+	// tests/vectors is vendored byte for byte from sdk-conformance: CI diffs it against the source.
+	"ignorePatterns": [".claude/settings.local.json", "CHANGELOG.md", "tests/vectors/**"],
 }

CLAUDE.md

@@ -22,7 +22,6 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Available Skills
 
-| Skill                 | Usage                       | Description                                        |
-| --------------------- | --------------------------- | -------------------------------------------------- |
-| **orama-integration** | N/A                         | Integrating with Orama search/indexing             |
-| **release-please**    | `/release-please <version>` | Trigger a release-please PR for a specific version |
+| Skill              | Usage                       | Description                                        |
+| ------------------ | --------------------------- | -------------------------------------------------- |
+| **release-please** | `/release-please <version>` | Trigger a release-please PR for a specific version |