Add Wave 1 SDKs and runnable examples

.github/workflows/ci.yml

@@ -24,5 +24,22 @@ jobs:
         with:
           node-version: "20"
 
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.22"
+
+      - name: Set up Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "17"
+          cache: maven
+
+      - name: Set up .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: "8.0.x"
+
       - name: Run PR quality gates
         run: bash scripts/ci/pr_checks.sh

.github/workflows/pr-ci.yml

@@ -12,22 +12,39 @@ jobs:
 
     steps:
       - name: Check out repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v5
         with:
           python-version: "3.13"
           cache: pip
           cache-dependency-path: python/pyproject.toml
 
       - name: Set up Node.js
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v4
         with:
           node-version: "22"
           cache: npm
           cache-dependency-path: typescript/package-lock.json
 
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.22"
+
+      - name: Set up Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "17"
+          cache: maven
+
+      - name: Set up .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: "8.0.x"
+
       - name: Run PR quality gates
         run: bash scripts/ci/pr_checks.sh
 

.gitignore

@@ -17,6 +17,13 @@ dist/
 coverage/
 *.tsbuildinfo
 
+# .NET
+bin/
+obj/
+
+# Java / Maven
+target/
+
 # IDE
 .idea/
 .vscode/

README.md

@@ -11,11 +11,14 @@
 <p align="center">
   <img src="https://img.shields.io/badge/Python-3.9+-blue.svg" />
   <img src="https://img.shields.io/badge/TypeScript-available-blue.svg" />
+  <img src="https://img.shields.io/badge/Go-preview-blue.svg" />
+  <img src="https://img.shields.io/badge/Java-17+-blue.svg" />
+  <img src="https://img.shields.io/badge/.NET-8.0-blue.svg" />
   <img src="https://img.shields.io/badge/Status-Public%20Preview-orange.svg" />
   <img src="https://img.shields.io/badge/License-MIT-green.svg" />
 </p>
 
-Python and TypeScript SDKs for AI agents and developers building on SynapseNetwork.
+Python, TypeScript, Go, Java, and .NET SDKs for AI agents and developers building on SynapseNetwork.
 
 SynapseNetwork lets an agent discover services, invoke them through a gateway, and settle the call with an auditable receipt. The fastest integration path is:
 
@@ -98,6 +101,37 @@ The SDK never probes DNS and never falls back between environments automatically
 
 Provider is an owner-scoped supply-side role, not a separate root account. Keep ordinary agent runtime code on `SynapseClient`; use `SynapseProvider` only when you are registering or operating services exposed through SynapseNetwork.
 
+## Official SDK Coverage
+
+| Language | Package path | Current coverage |
+|---|---|---|
+| Python | `python/` | Consumer, owner auth, provider publishing |
+| TypeScript | `typescript/` | Consumer, owner auth, provider publishing |
+| Go | `go/` | Consumer runtime preview |
+| Java/JVM | `java/` | Consumer runtime preview; Kotlin can call the Java SDK |
+| .NET | `dotnet/` | Consumer runtime preview |
+
+Wave 1 multi-language SDKs focus on agent runtime: search/discover, fixed-price invoke, token-metered LLM invoke, receipt lookup, and gateway health. Owner auth and provider publishing for Go, Java, and .NET are planned after the consumer runtime surface is stable.
+
+## Examples By SDK
+
+All runnable examples default to staging and read `SYNAPSE_AGENT_KEY`.
+
+| SDK | Free fixed-price smoke | LLM smoke | Full local E2E |
+|---|---|---|---|
+| Python | `PYTHONPATH=python python3 python/examples/free_service_smoke.py` | `PYTHONPATH=python python3 python/examples/llm_smoke.py` | `PYTHONPATH=python python3 python/examples/e2e.py` |
+| TypeScript | `npm run example:free --prefix typescript` | `npm run example:llm --prefix typescript` | `npm run example:e2e --prefix typescript` |
+| Go | `go -C go run ./examples/free_service_smoke` | `go -C go run ./examples/llm_smoke` | `go -C go run ./examples/e2e` |
+| Java/JVM | `mvn -q -f java/examples/pom.xml exec:java -Dexec.mainClass=ai.synapsenetwork.sdk.examples.FreeServiceSmoke` | `mvn -q -f java/examples/pom.xml exec:java -Dexec.mainClass=ai.synapsenetwork.sdk.examples.LlmSmoke` | `mvn -q -f java/examples/pom.xml exec:java -Dexec.mainClass=ai.synapsenetwork.sdk.examples.E2eSmoke` |
+| .NET | `dotnet run --project dotnet/examples/free-service-smoke/free-service-smoke.csproj` | `dotnet run --project dotnet/examples/llm-smoke/llm-smoke.csproj` | `dotnet run --project dotnet/examples/e2e/e2e.csproj` |
+
+To run every SDK through the same real Gateway E2E harness:
+
+```bash
+export SYNAPSE_AGENT_KEY=agt_xxx
+bash scripts/e2e/sdk_wave1_local.sh --skip-install
+```
+
 ## Agent Quickstart: Python
 
 Step 1: get your Agent Key from the Synapse Gateway Dashboard.
@@ -295,6 +329,15 @@ The Python examples are staging-first and live under `python/examples`.
 cd python
 ```
 
+Run consumer smoke examples:
+
+```bash
+export SYNAPSE_AGENT_KEY=agt_xxx
+PYTHONPATH="$PWD" .venv/bin/python examples/free_service_smoke.py
+PYTHONPATH="$PWD" .venv/bin/python examples/llm_smoke.py
+PYTHONPATH="$PWD" .venv/bin/python examples/e2e.py
+```
+
 Register a provider service on staging:
 
 ```bash

README.zh-CN.md

@@ -11,11 +11,14 @@
 <p align="center">
   <img src="https://img.shields.io/badge/Python-3.9+-blue.svg" />
   <img src="https://img.shields.io/badge/TypeScript-available-blue.svg" />
+  <img src="https://img.shields.io/badge/Go-preview-blue.svg" />
+  <img src="https://img.shields.io/badge/Java-17+-blue.svg" />
+  <img src="https://img.shields.io/badge/.NET-8.0-blue.svg" />
   <img src="https://img.shields.io/badge/Status-Public%20Preview-orange.svg" />
   <img src="https://img.shields.io/badge/License-MIT-green.svg" />
 </p>
 
-面向 AI Agent 和开发者的 SynapseNetwork Python / TypeScript SDK。
+面向 AI Agent 和开发者的 SynapseNetwork Python / TypeScript / Go / Java / .NET SDK。
 
 SynapseNetwork 让 Agent 可以发现服务、通过 gateway 调用服务，并用可审计 receipt 完成结算验证。最快接入路径是：
 
@@ -98,6 +101,37 @@ SDK 不会自动探测 DNS，也不会在环境之间自动 fallback。这样可
 
 Provider 是 owner scope 下的供给侧角色，不是第二套根账户体系。普通 Agent runtime 代码保持使用 `SynapseClient`；只有注册或运营 SynapseNetwork 服务时才使用 `SynapseProvider`。
 
+## 官方 SDK 覆盖范围
+
+| 语言 | 包路径 | 当前覆盖 |
+|---|---|---|
+| Python | `python/` | Consumer、owner auth、provider publishing |
+| TypeScript | `typescript/` | Consumer、owner auth、provider publishing |
+| Go | `go/` | Consumer runtime preview |
+| Java/JVM | `java/` | Consumer runtime preview；Kotlin 可直接调用 Java SDK |
+| .NET | `dotnet/` | Consumer runtime preview |
+
+Wave 1 多语言 SDK 先聚焦 Agent runtime：search/discover、fixed-price invoke、token-metered LLM invoke、receipt lookup 和 gateway health。Go、Java、.NET 的 owner auth 与 provider publishing 会在 consumer runtime 稳定后进入下一阶段。
+
+## 各 SDK 示例
+
+所有 runnable examples 默认使用 staging，并读取 `SYNAPSE_AGENT_KEY`。
+
+| SDK | 免费 fixed-price smoke | LLM smoke | 完整本地 E2E |
+|---|---|---|---|
+| Python | `PYTHONPATH=python python3 python/examples/free_service_smoke.py` | `PYTHONPATH=python python3 python/examples/llm_smoke.py` | `PYTHONPATH=python python3 python/examples/e2e.py` |
+| TypeScript | `npm run example:free --prefix typescript` | `npm run example:llm --prefix typescript` | `npm run example:e2e --prefix typescript` |
+| Go | `go -C go run ./examples/free_service_smoke` | `go -C go run ./examples/llm_smoke` | `go -C go run ./examples/e2e` |
+| Java/JVM | `mvn -q -f java/examples/pom.xml exec:java -Dexec.mainClass=ai.synapsenetwork.sdk.examples.FreeServiceSmoke` | `mvn -q -f java/examples/pom.xml exec:java -Dexec.mainClass=ai.synapsenetwork.sdk.examples.LlmSmoke` | `mvn -q -f java/examples/pom.xml exec:java -Dexec.mainClass=ai.synapsenetwork.sdk.examples.E2eSmoke` |
+| .NET | `dotnet run --project dotnet/examples/free-service-smoke/free-service-smoke.csproj` | `dotnet run --project dotnet/examples/llm-smoke/llm-smoke.csproj` | `dotnet run --project dotnet/examples/e2e/e2e.csproj` |
+
+统一跑全部 SDK：
+
+```bash
+export SYNAPSE_AGENT_KEY=agt_xxx
+bash scripts/e2e/sdk_wave1_local.sh --skip-install
+```
+
 ## Agent 快速接入：Python
 
 步骤 1：从 Synapse Gateway Dashboard 获取 Agent Key。

contracts/sdk/fixtures/discovery_search_response.json

@@ -0,0 +1,23 @@
+{
+  "requestId": "req_contract_discovery",
+  "count": 1,
+  "page": 1,
+  "pageSize": 10,
+  "totalCount": 1,
+  "hasMore": false,
+  "results": [
+    {
+      "serviceId": "svc_contract_weather",
+      "serviceName": "Contract Weather",
+      "status": "active",
+      "serviceKind": "api",
+      "priceModel": "fixed",
+      "pricing": {
+        "amount": "0.010000",
+        "currency": "USDC"
+      },
+      "summary": "Fixture service for SDK contract tests.",
+      "tags": ["fixture", "free"]
+    }
+  ]
+}

contracts/sdk/fixtures/error_budget_exhausted.json

@@ -0,0 +1,6 @@
+{
+  "detail": {
+    "code": "CREDENTIAL_CREDIT_LIMIT_EXCEEDED",
+    "message": "Agent credential budget is exhausted."
+  }
+}

contracts/sdk/fixtures/error_price_mismatch.json

@@ -0,0 +1,8 @@
+{
+  "detail": {
+    "code": "PRICE_MISMATCH",
+    "message": "Live price changed. Rediscover before retrying.",
+    "expectedPriceUsdc": "0.010000",
+    "currentPriceUsdc": "0.012000"
+  }
+}

contracts/sdk/fixtures/fixed_price_invoke_response.json

@@ -0,0 +1,12 @@
+{
+  "invocationId": "inv_contract_fixed",
+  "status": "SUCCEEDED",
+  "chargedUsdc": "0.010000",
+  "result": {
+    "temperature": 72,
+    "unit": "fahrenheit"
+  },
+  "receipt": {
+    "invocationId": "inv_contract_fixed"
+  }
+}

contracts/sdk/fixtures/llm_invoke_response.json

@@ -0,0 +1,19 @@
+{
+  "invocationId": "inv_contract_llm",
+  "status": "SUCCEEDED",
+  "chargedUsdc": "0.004200",
+  "usage": {
+    "inputTokens": 120,
+    "outputTokens": 32,
+    "totalTokens": 152
+  },
+  "synapse": {
+    "priceModel": "token_metered",
+    "holdUsdc": "0.010000",
+    "chargedUsdc": "0.004200",
+    "releasedUsdc": "0.005800"
+  },
+  "result": {
+    "content": "contract llm response"
+  }
+}

contracts/sdk/fixtures/receipt_response.json

@@ -0,0 +1,9 @@
+{
+  "invocationId": "inv_contract_fixed",
+  "status": "SETTLED",
+  "chargedUsdc": "0.010000",
+  "result": {
+    "temperature": 72,
+    "unit": "fahrenheit"
+  }
+}