feat(repo): Add new Go SDK

.github/workflows/ci.yml

@@ -155,6 +155,7 @@ jobs:
           filters: |
             backend:
               - '**/*.go'
+              - 'magefile.go'
               - 'go.mod'
               - 'go.sum'
               - 'Makefile'
@@ -198,6 +199,11 @@ jobs:
       - name: Setup git-cliff for release tests
         uses: ./.github/actions/setup-git-cliff
 
+      - name: Install Mage
+        run: |
+          echo "Installing Mage..."
+          go install github.com/magefile/mage@latest
+
       - name: Run linting
         run: |
           echo "Running Go code quality checks..."
@@ -222,6 +228,23 @@ jobs:
           make test
         continue-on-error: false
 
+      - name: Run SDK benchmarks
+        run: |
+          echo "Running SDK benchmarks with memory stats..."
+          go test -run=^$ -bench=. -benchmem github.com/compozy/compozy/sdk/agent \
+            github.com/compozy/compozy/sdk/project \
+            github.com/compozy/compozy/sdk/workflow \
+            github.com/compozy/compozy/sdk/task \
+            github.com/compozy/compozy/sdk/knowledge \
+            github.com/compozy/compozy/sdk/memory \
+            github.com/compozy/compozy/sdk/compozy | tee bench.out
+        continue-on-error: false
+
+      - name: Check benchmark regressions
+        run: |
+          go run ./tools/benchcheck --baseline sdk/docs/performance-benchmarks.json --results bench.out
+        continue-on-error: false
+
       - name: Upload test results
         uses: actions/upload-artifact@v4
         if: always()

.github/workflows/coverage.yml

@@ -47,10 +47,30 @@ jobs:
         run: |
           make test-coverage
 
+      - name: Generate SDK coverage report
+        run: |
+          go work sync
+          cd sdk
+          packages=$(go list ./... 2>/dev/null | grep -v '/examples')
+          if [ -z "$packages" ]; then
+            echo "no SDK packages discovered"
+            exit 1
+          fi
+          go test -covermode=atomic -coverprofile=coverage.out $packages
+
+      - name: Enforce SDK coverage
+        run: |
+          cd sdk
+          go tool cover -func=coverage.out | tee coverage.txt
+          awk '/^total:/ {gsub(/%/, "", $3); cov=$3+0; if (cov < 100) {printf "Coverage is %.2f%%, must be 100%%\n", cov; exit 1}} END {if (NR == 0) {print "No coverage summary found"; exit 1}}' coverage.txt
+          echo "SDK coverage requirement satisfied"
+
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v5
         with:
-          files: ./coverage.out
+          files: |
+            ./coverage.out
+            ./sdk/coverage.out
           flags: unittests
           name: codecov-umbrella
           fail_ci_if_error: true

.github/workflows/release.yml

@@ -39,7 +39,6 @@ env:
   NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
   NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
   PR_RELEASE_MODULE: github.com/compozy/releasepr@v0.0.15
-  GOTMPDIR: ${{ runner.temp }}/go-tmp
 
 permissions:
   contents: write
@@ -61,15 +60,15 @@ jobs:
        github.event.head_commit.author.name != 'github-actions[bot]') ||
       (github.event_name == 'workflow_dispatch')
     runs-on: ubuntu-latest
-    env:
-      GOTMPDIR: ${{ env.GOTMPDIR }}
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
           fetch-tags: true
 
       - name: Prepare Go temporary directory
+        env:
+          GOTMPDIR: ${{ runner.temp }}/go-tmp
         run: mkdir -p "$GOTMPDIR"
 
       - uses: ./.github/actions/setup-go
@@ -86,6 +85,7 @@ jobs:
           GITHUB_REPOSITORY: ${{ github.repository }}
           GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }}
           INITIAL_VERSION: ${{ env.INITIAL_VERSION }}
+          GOTMPDIR: ${{ runner.temp }}/go-tmp
         run: |
           go run "${{ env.PR_RELEASE_MODULE }}" pr-release --force --enable-rollback --ci-output
 
@@ -97,15 +97,15 @@ jobs:
       (startsWith(github.event.pull_request.title, 'ci(release): Release ') ||
        startsWith(github.base_ref, 'release/v'))
     runs-on: ubuntu-latest
-    env:
-      GOTMPDIR: ${{ env.GOTMPDIR }}
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
           fetch-tags: true
 
       - name: Prepare Go temporary directory
+        env:
+          GOTMPDIR: ${{ runner.temp }}/go-tmp
         run: mkdir -p "$GOTMPDIR"
 
       - uses: ./.github/actions/setup-go
@@ -130,6 +130,7 @@ jobs:
           GITHUB_HEAD_REF: ${{ github.head_ref }}
           GITHUB_ISSUE_NUMBER: ${{ github.event.pull_request.number }}
           GORELEASER_KEY: ${{ secrets.GORELEASER_KEY }}
+          GOTMPDIR: ${{ runner.temp }}/go-tmp
         run: go run "${{ env.PR_RELEASE_MODULE }}" dry-run --ci-output
 
   # Job 3: Production release on merge
@@ -143,14 +144,15 @@ jobs:
     timeout-minutes: 120
     env:
       DOCKER_CLI_EXPERIMENTAL: enabled
-      GOTMPDIR: ${{ env.GOTMPDIR }}
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
           fetch-tags: true
 
       - name: Prepare Go temporary directory
+        env:
+          GOTMPDIR: ${{ runner.temp }}/go-tmp
         run: mkdir -p "$GOTMPDIR"
 
       - name: Set up Go with caching
@@ -212,6 +214,7 @@ jobs:
           AUR_KEY: ${{ secrets.AUR_KEY }}
           COSIGN_EXPERIMENTAL: 1
           GORELEASER_KEY: ${{ secrets.GORELEASER_KEY }}
+          GOTMPDIR: ${{ runner.temp }}/go-tmp
 
       - name: Publish NPM Packages
         env:

.github/workflows/test-sdk.yml

@@ -0,0 +1,179 @@
+name: SDK Tests
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "sdk/**"
+      - "go.work"
+      - ".github/workflows/test-sdk.yml"
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "sdk/**"
+      - "go.work"
+      - ".github/workflows/test-sdk.yml"
+  workflow_dispatch:
+
+env:
+  GO_VERSION: "1.25.2"
+
+jobs:
+  unit:
+    name: SDK Unit Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go with caching
+        uses: ./.github/actions/setup-go
+        with:
+          go-version: ${{ env.GO_VERSION }}
+          install-tools: "false"
+
+      - name: Initialize Go workspace
+        run: |
+          rm -f go.work
+          go work init . ./sdk
+          go work sync
+
+      - name: Download SDK dependencies
+        run: |
+          cd sdk
+          go mod download
+          go mod verify
+
+      - name: Run unit tests with race detector and coverage
+        run: |
+          cd sdk
+          packages=$(go list ./... 2>/dev/null | grep -v '/examples')
+          if [ -z "$packages" ]; then
+            echo "no SDK packages discovered"
+            exit 1
+          fi
+          go test -race -covermode=atomic -coverprofile=coverage.out $packages
+
+      - name: Enforce 100% coverage
+        run: |
+          cd sdk
+          go tool cover -func=coverage.out | tee coverage.txt
+          awk '/^total:/ {gsub(/%/, "", $3); cov=$3+0; if (cov < 100) {printf "Coverage is %.2f%%, must be 100%%\n", cov; exit 1}} END {if (NR == 0) {print "No coverage summary found"; exit 1}}' coverage.txt
+          echo "Coverage requirement satisfied"
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          files: sdk/coverage.out
+          flags: sdk-unit
+          name: sdk-unit
+          fail_ci_if_error: true
+          token: ${{ secrets.CODECOV_TOKEN }}
+          override_branch: ${{ github.head_ref || github.ref_name }}
+          override_commit: ${{ github.event.pull_request.head.sha || github.sha }}
+
+  integration:
+    name: SDK Integration Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 40
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go with caching
+        uses: ./.github/actions/setup-go
+        with:
+          go-version: ${{ env.GO_VERSION }}
+          install-tools: "false"
+
+      - name: Initialize Go workspace
+        run: |
+          rm -f go.work
+          go work init . ./sdk
+          go work sync
+
+      - name: Run integration tests
+        run: |
+          cd sdk
+          packages=$(go list ./... 2>/dev/null | grep -v '/examples')
+          if [ -z "$packages" ]; then
+            echo "no SDK packages discovered"
+            exit 0
+          fi
+          go test -count=1 -tags=integration $packages
+        env:
+          TESTCONTAINERS_RYUK_DISABLED: "false"
+          TESTCONTAINERS_CLEANUP_TIMEOUT: "120s"
+
+  benchmarks:
+    name: SDK Benchmarks
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Go with caching
+        uses: ./.github/actions/setup-go
+        with:
+          go-version: ${{ env.GO_VERSION }}
+          install-tools: "false"
+
+      - name: Initialize Go workspace
+        run: |
+          rm -f go.work
+          go work init . ./sdk
+          go work sync
+
+      - name: Run benchmarks
+        run: |
+          cd sdk
+          packages=$(go list ./... 2>/dev/null | grep -v '/examples')
+          if [ -z "$packages" ]; then
+            echo "no SDK packages discovered"
+            exit 0
+          fi
+          go test -run=^$ -bench=. -benchmem $packages | tee bench.out
+
+      - name: Detect benchmark regressions
+        run: |
+          go run ./tools/benchcheck --baseline sdk/docs/performance-benchmarks.json --results sdk/bench.out
+
+      - name: Upload benchmark results
+        uses: actions/upload-artifact@v4
+        with:
+          name: sdk-benchmarks
+          path: sdk/bench.out
+          retention-days: 7
+
+  lint:
+    name: SDK Lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Go with caching
+        uses: ./.github/actions/setup-go
+        with:
+          go-version: ${{ env.GO_VERSION }}
+          install-tools: "false"
+
+      - name: Initialize Go workspace
+        run: |
+          rm -f go.work
+          go work init . ./sdk
+          go work sync
+
+      - name: Run golangci-lint
+        uses: golangci/golangci-lint-action@v8
+        with:
+          version: latest
+          working-directory: sdk
+          args: --timeout=5m

.golangci.yml

@@ -80,6 +80,9 @@ linters:
           - lll
           - unparam
         path: _test\.go
+      - linters:
+          - funlen
+        path: sdk/examples
       - linters:
           - dupl
         path: pkg/pb

AGENTS.md

@@ -55,6 +55,10 @@ cat .cursor/rules/{go-coding-standards,architecture,test-standards,backwards-com
   - **Linting:** `golangci-lint run --fix --allow-parallel-runners <scope>` (e.g., `./engine/agent/...`)
   - **IF YOUR SCOPE** is `.../.` then you need to run `make test` and `make lint`
 
+### When writting code
+
+- **YOU MUST STRICTLY** follow the .cursor/rules/no-linebreaks.mdc or your code will be invalidate
+
 **Enforcement:** Violating these standards results in immediate task rejection.
 </critical>
 

CLAUDE.md

@@ -55,6 +55,10 @@ cat .cursor/rules/{go-coding-standards,architecture,test-standards,backwards-com
   - **Linting:** `golangci-lint run --fix --allow-parallel-runners <scope>` (e.g., `./engine/agent/...`)
   - **IF YOUR SCOPE** is `.../.` then you need to run `make test` and `make lint`
 
+### When writting code
+
+- **YOU MUST STRICTLY** follow the .cursor/rules/no-linebreaks.mdc or your code will be invalidate
+
 **Enforcement:** Violating these standards results in immediate task rejection.
 </critical>
 

GEMINI.md

@@ -55,6 +55,10 @@ cat .cursor/rules/{go-coding-standards,architecture,test-standards,backwards-com
   - **Linting:** `golangci-lint run --fix --allow-parallel-runners <scope>` (e.g., `./engine/agent/...`)
   - **IF YOUR SCOPE** is `.../.` then you need to run `make test` and `make lint`
 
+### When writting code
+
+- **YOU MUST STRICTLY** follow the .cursor/rules/no-linebreaks.mdc or your code will be invalidate
+
 **Enforcement:** Violating these standards results in immediate task rejection.
 </critical>