@chaoschain/sdk 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.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

@@ -102,6 +102,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 +1220,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 +1243,28 @@ AGENT_ADDRESS=0x... \
 npx tsx scripts/test-session-e2e.ts
 ```
 
-**Required Environment Variables:**
+### Multi-agent mode
 
-- `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
+Set `OVERRIDE_AGENT_ADDRESS` to run three additional collaborator events (per-event `agent` override). Pass when `node_count >= 7`.
+
+```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/index.cjs

@@ -15442,7 +15442,10 @@ var Session = class {
       causality: {
         parent_event_ids: this.lastEventId ? [this.lastEventId] : []
       },
-      agent: { agent_address: this.agentAddress, role: "worker" },
+      agent: {
+        agent_address: opts.agent?.agent_address ?? this.agentAddress,
+        role: opts.agent?.role ?? "worker"
+      },
       studio: {
         studio_address: this.studioAddress,
         studio_policy_version: this.studioPolicyVersion
@@ -15472,9 +15475,9 @@ var Session = class {
    * @param stepType - Friendly step name.
    * @param summary - What happened in this step.
    */
-  async step(stepType, summary) {
+  async step(stepType, summary, agent) {
     const eventType = STEP_TYPE_MAP[stepType] ?? "artifact_created";
-    await this.log({ event_type: eventType, summary });
+    await this.log({ event_type: eventType, summary, agent });
   }
   /**
    * Complete the session.
@@ -16182,7 +16185,7 @@ var ChaosChainSDK = class _ChaosChainSDK {
    * Get SDK version
    */
   getVersion() {
-    return "0.3.0";
+    return "0.3.1";
   }
   /**
    * Get SDK capabilities summary
@@ -16980,7 +16983,7 @@ function verifyWorkEvidence(evidence, context) {
 }
 
 // src/index.ts
-var SDK_VERSION = "0.3.0";
+var SDK_VERSION = "0.3.1";
 var ERC8004_VERSION = "1.0";
 var X402_VERSION = "1.0";
 var src_default = ChaosChainSDK;