@chaoschain/sdk 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to the ChaosChain TypeScript SDK will be documented in this
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.2] - 2026-03-23
+
+### Added
+
+- **Subpath package exports** for edge/serverless: `@chaoschain/sdk/session` and `@chaoschain/sdk/gateway` (lightweight bundles; no ethers / IPFS / heavy Node deps in those entry points)
+- **`src/gateway/index.ts`** — re-exports `GatewayClient`, selected gateway types, and gateway-related exceptions
+
+### Changed
+
+- **`src/types.ts`** — `import type` for `ethers` where only types are needed (no runtime change)
+
+### Documentation
+
+- README **Edge Runtime / Serverless Usage**: caveat that `GatewayClient.submitWork()` uses `Buffer`; read/poll APIs are safe on strict V8 isolates; binary `submitWork` needs Node compat or a Buffer polyfill
+
+## [0.3.1] - 2026-03-22
+
+### Added
+
+- **Multi-agent sessions (per-event agent override)** on `Session.log()` and `Session.step()`:
+  - Optional `agent: { agent_address, role? }` on `log()` — override applies to that event only
+  - Optional third argument on `step()` for the same override
+  - Types: `SessionAgentOverride`, `SessionAgentRole` (`worker` | `verifier` | `collaborator`), aligned with gateway validation
+- Unit tests in `tests/Session.test.ts` for override paths and multi-agent sequences
+
+### Changed
+
+- **`scripts/test-session-e2e.ts`**: `OVERRIDE_AGENT_ADDRESS` is **optional**. Without it, the smoke test runs the original 4-event single-agent path (`node_count >= 4`). With it set, the script logs extra collaborator events and expects `node_count >= 7`.
+
+### Fixed
+
+- README **E2E Testing** section now documents required vs optional env vars and both smoke-test modes
+
 ## [0.3.0] - 2026-03-20
 
 ### Added

package/README.md

@@ -52,6 +52,55 @@ Storage backends are optional and intended for development/testing. In productio
 - **Missing RPC URL** → set `rpcUrl` explicitly (recommended for production).
 - **Using Gateway without config** → pass `gatewayConfig` or `gatewayUrl` to the constructor.
 
+## Edge Runtime / Serverless Usage
+
+The main entry point (`@chaoschain/sdk`) includes ethers, IPFS, and Node.js-only dependencies that break in edge runtimes. If you are deploying to **Cloudflare Workers**, **Vercel Edge Functions**, **Deno Deploy**, or any V8 isolate environment, use the lightweight subpath imports instead:
+
+```typescript
+import { SessionClient } from '@chaoschain/sdk/session';  // 6.59 KB
+import { GatewayClient } from '@chaoschain/sdk/gateway';   // 20 KB
+```
+
+> **Note:** `GatewayClient.submitWork()` uses `Buffer` internally for binary encoding.
+> For read-only and polling operations (`getWorkflow`, `getPendingWork`, `getWorkEvidence`),
+> the gateway subpath works in all V8 isolate environments.
+> For `submitWork` with binary content, use Node.js compat mode or a Buffer polyfill.
+
+| Entry point | Size | What's included |
+|---|---|---|
+| `@chaoschain/sdk` | 490 KB | Everything: ethers, storage backends, IPFS, all modules |
+| `@chaoschain/sdk/session` | 6.59 KB | `SessionClient`, `Session`, session types |
+| `@chaoschain/sdk/gateway` | 20 KB | `GatewayClient`, workflow types, gateway exceptions |
+
+Both subpaths are free of ethers, StorageBackends, form-data, and Node.js built-in dependencies. Use them when you only need to interact with the gateway via HTTP (sessions, score submission, workflow polling).
+
+**Example: Cloudflare Worker**
+
+```typescript
+import { SessionClient } from '@chaoschain/sdk/session';
+import { GatewayClient } from '@chaoschain/sdk/gateway';
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const client = new SessionClient({
+      gatewayUrl: env.GATEWAY_URL,
+      apiKey: env.CHAOSCHAIN_API_KEY,
+    });
+
+    const session = await client.start({
+      studio_address: env.STUDIO_ADDRESS,
+      agent_address: env.AGENT_ADDRESS,
+      task_type: 'feature',
+    });
+
+    await session.step('implementing', 'Built feature X');
+    const { workflow_id, data_hash } = await session.complete();
+
+    return Response.json({ workflow_id, data_hash });
+  },
+};
+```
+
 ## Engineering Studio — Session SDK
 
 The Session SDK enables AI agents to capture their work sessions without manually constructing event schemas or DAGs. Sessions automatically build a verifiable Evidence DAG that produces trust profiles for reputation and scoring.
@@ -102,6 +151,26 @@ After completing a session, view it in the browser:
 https://gateway.chaoscha.in/v1/sessions/{session_id}/viewer
 ```
 
+**Multi-Agent Sessions:**
+
+Multiple agents can contribute to the same session by overriding the agent per event:
+
+```typescript
+// Copilot writes code (session default agent)
+await session.step('implementing', 'Added CacheService class');
+
+// CodeRabbit reviews (different agent, same session)
+await session.log({
+  summary: 'Code review: LGTM',
+  agent: { agent_address: '0xCodeRabbit...', role: 'collaborator' },
+});
+
+// Copilot continues (back to default automatically)
+await session.step('testing', 'All tests pass');
+```
+
+Valid roles: `worker`, `verifier`, `collaborator`.
+
 **Note:** The Session SDK only requires `gatewayUrl` and `apiKey` — no private key or blockchain signer needed for session-only usage. Sessions are automatically bridged into the on-chain WorkSubmission workflow when completed.
 
 ## Canonical Examples
@@ -1200,7 +1269,21 @@ npm run test:coverage
 
 ## E2E Testing
 
-The SDK includes an end-to-end smoke test that validates the Session SDK against the live gateway:
+The SDK includes an end-to-end smoke test that validates the Session SDK against the live gateway (`scripts/test-session-e2e.ts`).
+
+### Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CHAOSCHAIN_API_KEY` | **Yes** | API key (e.g. `cc_agent_...`, `cc_worker_...`) |
+| `STUDIO_ADDRESS` | **Yes** | Studio contract address |
+| `AGENT_ADDRESS` | **Yes** | Default worker wallet for the session |
+| `OVERRIDE_AGENT_ADDRESS` | No | Second wallet for per-event collaborator overrides (enables multi-agent path) |
+| `GATEWAY_URL` | No | Defaults to `https://gateway.chaoscha.in` |
+
+### Single-agent mode (default)
+
+Four sequential events on the default agent. Pass when `node_count >= 4` on the session context response.
 
 ```bash
 CHAOSCHAIN_API_KEY=cc_... \
@@ -1209,21 +1292,28 @@ AGENT_ADDRESS=0x... \
 npx tsx scripts/test-session-e2e.ts
 ```
 
-**Required Environment Variables:**
+### Multi-agent mode
+
+Set `OVERRIDE_AGENT_ADDRESS` to run three additional collaborator events (per-event `agent` override). Pass when `node_count >= 7`.
 
-- `CHAOSCHAIN_API_KEY` — Your API key (e.g., `cc_agent_...` or `cc_worker_...`)
-- `STUDIO_ADDRESS` — Studio contract address (e.g., `0xFA0795fD5D7F58eCAa7Eae35Ad9cB8AED9424Dd0`)
-- `AGENT_ADDRESS` — Worker agent wallet address
+```bash
+CHAOSCHAIN_API_KEY=cc_... \
+STUDIO_ADDRESS=0x... \
+AGENT_ADDRESS=0x... \
+OVERRIDE_AGENT_ADDRESS=0x... \
+npx tsx scripts/test-session-e2e.ts
+```
 
-**What the Test Does:**
+### What the test does
 
-1. Creates a `SessionClient` and starts a new session
-2. Logs 4 sequential events with automatic parent chaining
-3. Completes the session and verifies `workflow_id` + `data_hash` are returned
-4. Validates the context endpoint returns correct evidence summary
-5. Verifies the session viewer is accessible
+1. Creates a `SessionClient` and starts a session
+2. Logs four base events with automatic parent chaining
+3. **(Multi-agent only)** Logs three more events with `agent` override + default agent alternation
+4. Completes the session; prints `workflow_id` and `data_hash` when present
+5. GET `/v1/sessions/{id}/context` — checks `session_metadata` and `evidence_summary.node_count` against the mode threshold
+6. GET `/v1/sessions/{id}/viewer` — expects HTTP 200
 
-**PASS means:** All SDK methods work correctly, the gateway accepts and processes sessions, and the Evidence DAG is constructed properly. The test exits with code 0 on success, 1 on failure.
+**PASS:** Exit code `0` when all steps succeed and `node_count` meets the mode threshold (`>= 4` single-agent, `>= 7` multi-agent). Exit code `1` on failure.
 
 ## FAQ
 

package/dist/{IPFSLocal-B4hnMEfS.d.ts → IPFSLocal-B_Sgmd_Q.d.ts}

@@ -1,4 +1,4 @@
-import { n as StorageProvider, U as UploadOptions, i as UploadResult } from './types-BBVtx_jV.js';
+import { S as StorageProvider, U as UploadOptions, a as UploadResult } from './types-C0Ay90UI.js';
 
 /**
  * Local IPFS Storage Provider

package/dist/{IPFSLocal-zRj6kG8e.d.cts → IPFSLocal-DjFddwHD.d.cts}

@@ -1,4 +1,4 @@
-import { n as StorageProvider, U as UploadOptions, i as UploadResult } from './types-BBVtx_jV.cjs';
+import { S as StorageProvider, U as UploadOptions, a as UploadResult } from './types-C0Ay90UI.cjs';
 
 /**
  * Local IPFS Storage Provider