@chaoschain/sdk 0.2.4 → 0.3.1

package/CHANGELOG.md

@@ -5,6 +5,59 @@ 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
+
+- **Session SDK** (`src/session/`): `SessionClient` and `Session` classes for Engineering Studio session ingestion
+  - `session.start()` — Create a new coding session
+  - `session.log()` — Log events with automatic parent chaining
+  - `session.step()` — Convenience wrapper mapping friendly names to canonical event types
+  - `session.complete()` — Complete session and get `workflow_id` + `data_hash`
+- Automatic `parent_event_id` chaining across sequential `log()` calls
+- `step()` helper maps friendly names (`planning`, `implementing`, `testing`, `debugging`, `completing`) to canonical event types
+- E2E smoke test script at `scripts/test-session-e2e.ts` for validating against live gateway
+- Session SDK accessible via `sdk.session` when gateway is configured
+- **Verifier Agent Support**: Complete PoA (Proof-of-Agency) scoring utilities for verifier agents
+  - `verifyWorkEvidence()` — Validate evidence DAG and extract deterministic signals
+  - `extractAgencySignals()` — Extract initiative, collaboration, reasoning signals from evidence
+  - `composeScoreVector()` — Compose final score vector with verifier judgment (compliance/efficiency required)
+  - `composeScoreVectorWithDefaults()` — Compose scores with fallback defaults
+  - `GatewayClient.getPendingWork()` — Discover pending work for a studio
+  - `GatewayClient.getWorkEvidence()` — Fetch full evidence graph for work submission
+  - Types: `AgencySignals`, `VerifierAssessment`, `WorkVerificationResult`, `EngineeringStudioPolicy`, `WorkMandate`
+- **Verifier Integration Guide** documentation with complete step-by-step workflow
+
+### Changed
+
+- **Gateway is now always configured by default**: SDK automatically creates a `GatewayClient` pointing to `https://gateway.chaoscha.in` when no `gatewayConfig` or `gatewayUrl` is provided. This is a **breaking change** for code that expected `sdk.gateway` to be `null` when not explicitly configured.
+- Gateway client initialization log now shows the resolved base URL
+- Updated README with comprehensive verifier agent integration examples and 3-layer PoA scoring architecture
+
+### Fixed
+
+- `randomUUID()` now uses `node:crypto` import for Node.js compatibility
+- **Treasury address correction**: Fixed incorrect treasury address for `base-sepolia` network in `X402PaymentManager` (changed from `0x8004AA63c570c570eBF15376c0dB199918BFe9Fb` to `0x20E7B2A2c8969725b88Dd3EF3a11Bc3353C83F70`)
+- TypeScript unused parameter warning in `computeComplianceSignal()` (renamed `observed` to `_observed`)
+
 ## [0.2.0] - Unreleased
 
 ### Added

package/README.md

@@ -11,6 +11,7 @@ The ChaosChain TypeScript SDK enables developers to build autonomous AI agents w
 - **ERC-8004 v1.0** ✅ **100% compliant** - on-chain identity, validation and reputation
 - **ChaosChain Studios** - Multi-agent collaboration with reputation and rewards
 - **Gateway Integration** - Workflow orchestration, crash recovery, and XMTP messaging
+- **Engineering Studio Sessions** - Capture agent work sessions with automatic Evidence DAG construction
 - **x402 payments** using Coinbase's HTTP 402 protocol
 - **Pluggable storage** - IPFS, Pinata, Irys, 0G Storage
 - **Type-safe** - Full TypeScript support with exported types
@@ -51,6 +52,78 @@ 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.
 
+## 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.
+
+**Quick Start:**
+
+```typescript
+import { SessionClient } from '@chaoschain/sdk';
+
+const client = new SessionClient({
+  gatewayUrl: 'https://gateway.chaoscha.in',
+  apiKey: process.env.CHAOSCHAIN_API_KEY,
+});
+
+// 1. Start a session
+const session = await client.start({
+  studio_address: '0xFA0795fD5D7F58eCAa7Eae35Ad9cB8AED9424Dd0',
+  agent_address: '0x9B4Cef62a0ce1671ccFEFA6a6D8cBFa165c49831',
+  task_type: 'feature',
+});
+
+// 2. Log events (automatic parent chaining)
+await session.log({ summary: 'Planning cache layer implementation' });
+
+// 3. Use step() for common workflows
+await session.step('implementing', 'Added CacheService class');
+await session.step('testing', 'All 47 tests pass');
+
+// 4. Complete and get workflow_id + data_hash
+const { workflow_id, data_hash } = await session.complete();
+```
+
+**step() Mappings:**
+
+| Friendly Name | Canonical Event Type |
+|--------------|---------------------|
+| `planning`    | `plan_created`      |
+| `implementing`| `file_written`      |
+| `testing`     | `test_run`          |
+| `debugging`   | `debug_step`         |
+| `completing`  | `submission_created`|
+
+**View Your Session:**
+
+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
 
 ### 0) Verifier agent (pending work → evidence → scores)
@@ -100,7 +173,20 @@ for (const work of pending.data.work) {
 
 **Full verifier flow** (registration, polling loop, reputation): see the [Verifier Integration Guide](https://github.com/ChaosChain/chaoschain/blob/main/docs/VERIFIER_INTEGRATION_GUIDE.md) (or `docs/VERIFIER_INTEGRATION_GUIDE.md` in the ChaosChain repo). Gateway base URL: `https://gateway.chaoscha.in`. Evidence endpoint requires an API key.
 
-### 1) Minimal “Happy Path” (Gateway-first)
+#### Recommended verifier flow
+
+Use `verifyWorkEvidence()` to validate the DAG and extract signals, then `composeScoreVector()` with your compliance and efficiency assessments:
+
+```typescript
+const result = verifyWorkEvidence(evidence, { studioPolicy, workMandate });
+
+const scores = composeScoreVector(result.signals, {
+  complianceScore: 0.87,
+  efficiencyScore: 0.81,
+});
+```
+
+### 1) Minimal "Happy Path" (Gateway-first)
 
 ```typescript
 import { ChaosChainSDK, NetworkConfig, AgentRole } from '@chaoschain/sdk';
@@ -1132,6 +1218,54 @@ npm test -- WalletManager.test.ts
 npm run test:coverage
 ```
 
+## E2E Testing
+
+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_... \
+STUDIO_ADDRESS=0x... \
+AGENT_ADDRESS=0x... \
+npx tsx scripts/test-session-e2e.ts
+```
+
+### Multi-agent mode
+
+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
+
+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:** 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
 
 **Q: Do I need to deploy contracts?**

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

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

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

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

package/dist/index.cjs

@@ -15393,6 +15393,189 @@ var StudioClient = class {
     return ethers.ethers.hexlify(ethers.ethers.randomBytes(32));
   }
 };
+var STEP_TYPE_MAP = {
+  planning: "plan_created",
+  testing: "test_run",
+  debugging: "debug_step",
+  implementing: "file_written",
+  completing: "submission_created"
+};
+var Session = class {
+  /** Session ID returned by the gateway. */
+  sessionId;
+  gatewayUrl;
+  apiKey;
+  studioAddress;
+  agentAddress;
+  studioPolicyVersion;
+  workMandateId;
+  taskType;
+  lastEventId;
+  /** @internal — use {@link SessionClient.start} to create instances. */
+  constructor(opts) {
+    this.sessionId = opts.sessionId;
+    this.gatewayUrl = opts.gatewayUrl;
+    this.apiKey = opts.apiKey;
+    this.lastEventId = opts.lastEventId ?? null;
+    this.studioAddress = opts.studioAddress;
+    this.agentAddress = opts.agentAddress;
+    this.studioPolicyVersion = opts.studioPolicyVersion;
+    this.workMandateId = opts.workMandateId;
+    this.taskType = opts.taskType;
+  }
+  /**
+   * Log a session event.
+   *
+   * Automatically generates `event_id`, `timestamp`, and chains `parent_event_ids`
+   * from the previous event so the gateway can build a causal DAG.
+   *
+   * @param opts - Event details. Only `summary` is required.
+   * @throws Error if the gateway returns a non-2xx status.
+   */
+  async log(opts) {
+    const eventId = crypto2.randomUUID();
+    const event = {
+      event_id: eventId,
+      event_type: opts.event_type ?? "artifact_created",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      summary: opts.summary,
+      causality: {
+        parent_event_ids: this.lastEventId ? [this.lastEventId] : []
+      },
+      agent: {
+        agent_address: opts.agent?.agent_address ?? this.agentAddress,
+        role: opts.agent?.role ?? "worker"
+      },
+      studio: {
+        studio_address: this.studioAddress,
+        studio_policy_version: this.studioPolicyVersion
+      },
+      task: {
+        work_mandate_id: this.workMandateId,
+        task_type: this.taskType
+      },
+      ...opts.metadata ? { metadata: opts.metadata } : {}
+    };
+    await this.post(`/v1/sessions/${this.sessionId}/events`, [event]);
+    this.lastEventId = eventId;
+  }
+  /**
+   * Convenience wrapper around {@link log} that maps human-friendly step names
+   * to canonical event types.
+   *
+   * Mappings:
+   * - `"planning"` → `plan_created`
+   * - `"testing"` → `test_run`
+   * - `"debugging"` → `debug_step`
+   * - `"implementing"` → `file_written`
+   * - `"completing"` → `submission_created`
+   *
+   * Unknown step types fall back to `artifact_created`.
+   *
+   * @param stepType - Friendly step name.
+   * @param summary - What happened in this step.
+   */
+  async step(stepType, summary, agent) {
+    const eventType = STEP_TYPE_MAP[stepType] ?? "artifact_created";
+    await this.log({ event_type: eventType, summary, agent });
+  }
+  /**
+   * Complete the session.
+   *
+   * Triggers the on-chain WorkSubmission workflow (if the gateway is configured for it)
+   * and returns `workflow_id` + `data_hash` for downstream verification/scoring.
+   *
+   * @param opts - Optional status (`"completed"` | `"failed"`) and summary.
+   * @returns `{ workflow_id, data_hash }` — both may be `null` if the gateway
+   *          workflow engine is not configured.
+   * @throws Error if the gateway returns a non-2xx status.
+   */
+  async complete(opts) {
+    const body = {};
+    if (opts?.status) body.status = opts.status;
+    if (opts?.summary) body.summary = opts.summary;
+    const data = await this.post(`/v1/sessions/${this.sessionId}/complete`, body);
+    return {
+      workflow_id: data.data?.workflow_id ?? null,
+      data_hash: data.data?.data_hash ?? null
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Internal HTTP helper
+  // ---------------------------------------------------------------------------
+  async post(path4, body) {
+    const url = `${this.gatewayUrl}${path4}`;
+    const headers = { "Content-Type": "application/json" };
+    if (this.apiKey) headers["X-API-Key"] = this.apiKey;
+    try {
+      const res = await axios2__default.default({ method: "POST", url, data: body, headers, timeout: 3e4 });
+      return res.data;
+    } catch (err) {
+      const axiosErr = err;
+      const status = axiosErr.response?.status ?? 0;
+      const detail = JSON.stringify(axiosErr.response?.data ?? axiosErr.message);
+      throw new Error(`Session request failed: POST ${path4} \u2192 ${status} ${detail}`);
+    }
+  }
+};
+
+// src/session/SessionClient.ts
+var SessionClient = class {
+  gatewayUrl;
+  apiKey;
+  constructor(config = {}) {
+    this.gatewayUrl = (config.gatewayUrl ?? "https://gateway.chaoscha.in").replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+  }
+  /**
+   * Create a new coding session on the gateway.
+   *
+   * Returns a {@link Session} instance that can be used to log events, run steps,
+   * and complete the session. The gateway persists all events and constructs the
+   * Evidence DAG automatically.
+   *
+   * @param opts - Session creation parameters.
+   * @returns A live {@link Session} bound to the newly created session ID.
+   * @throws Error if the gateway returns a non-2xx status.
+   */
+  async start(opts) {
+    const body = {
+      studio_address: opts.studio_address,
+      agent_address: opts.agent_address
+    };
+    if (opts.work_mandate_id) body.work_mandate_id = opts.work_mandate_id;
+    if (opts.task_type) body.task_type = opts.task_type;
+    if (opts.studio_policy_version) body.studio_policy_version = opts.studio_policy_version;
+    if (opts.session_id) body.session_id = opts.session_id;
+    const url = `${this.gatewayUrl}/v1/sessions`;
+    const headers = { "Content-Type": "application/json" };
+    if (this.apiKey) headers["X-API-Key"] = this.apiKey;
+    let data;
+    try {
+      const res = await axios2__default.default({ method: "POST", url, data: body, headers, timeout: 3e4 });
+      data = res.data;
+    } catch (err) {
+      const axiosErr = err;
+      const status = axiosErr.response?.status ?? 0;
+      const detail = JSON.stringify(axiosErr.response?.data ?? axiosErr.message);
+      throw new Error(`Failed to create session: POST /v1/sessions \u2192 ${status} ${detail}`);
+    }
+    const sessionId = data.data?.session_id;
+    if (!sessionId) {
+      throw new Error("Gateway response missing session_id");
+    }
+    return new Session({
+      sessionId,
+      gatewayUrl: this.gatewayUrl,
+      apiKey: this.apiKey,
+      studioAddress: opts.studio_address,
+      agentAddress: opts.agent_address,
+      studioPolicyVersion: opts.studio_policy_version ?? "engineering-studio-default-v1",
+      workMandateId: opts.work_mandate_id ?? "generic-task",
+      taskType: opts.task_type ?? "general"
+    });
+  }
+};
 
 // src/ChaosChainSDK.ts
 var ChaosChainSDK = class _ChaosChainSDK {
@@ -15410,8 +15593,10 @@ var ChaosChainSDK = class _ChaosChainSDK {
   a2aX402Extension;
   processIntegrity;
   mandateManager;
-  // Gateway client for workflow submission (optional)
-  gateway = null;
+  // Gateway client for workflow submission (always initialized)
+  gateway;
+  /** Session client for Engineering Studio session management. */
+  session;
   // Studio client for direct on-chain operations
   studio;
   // Configuration
@@ -15576,7 +15761,10 @@ var ChaosChainSDK = class _ChaosChainSDK {
     const gatewayConfig = config.gatewayConfig ?? (config.gatewayUrl ? { gatewayUrl: config.gatewayUrl } : {});
     this.gateway = new GatewayClient(gatewayConfig);
     const gatewayBaseUrl = gatewayConfig.baseUrl ?? gatewayConfig.gatewayUrl ?? "https://gateway.chaoscha.in";
-    console.log(`\u{1F310} Gateway client initialized: ${gatewayBaseUrl}`);
+    this.session = new SessionClient({
+      gatewayUrl: gatewayBaseUrl,
+      apiKey: gatewayConfig.auth?.apiKey
+    });
     this.studio = new StudioClient({
       provider: this.provider,
       signer: this.walletManager.getWallet(),
@@ -15589,16 +15777,6 @@ var ChaosChainSDK = class _ChaosChainSDK {
       );
       _ChaosChainSDK.warnedStudioClientProduction = true;
     }
-    console.log(`\u{1F680} ChaosChain SDK initialized for ${this.agentName}`);
-    console.log(`   Network: ${this.network}`);
-    console.log(`   Wallet: ${this.walletManager.getAddress()}`);
-    console.log(`   Features:`);
-    console.log(`     - ERC-8004: \u2705`);
-    console.log(`     - x402 Payments: ${this.x402PaymentManager ? "\u2705" : "\u274C"}`);
-    console.log(`     - Multi-Payment: ${this.paymentManager ? "\u2705" : "\u274C"}`);
-    console.log(`     - Google AP2: ${this.googleAP2 ? "\u2705" : "\u274C"}`);
-    console.log(`     - Process Integrity: ${this.processIntegrity ? "\u2705" : "\u274C"}`);
-    console.log(`     - Storage: \u2705`);
   }
   // ============================================================================
   // ERC-8004 Identity Methods
@@ -16007,7 +16185,7 @@ var ChaosChainSDK = class _ChaosChainSDK {
    * Get SDK version
    */
   getVersion() {
-    return "0.2.4";
+    return "0.3.1";
   }
   /**
    * Get SDK capabilities summary
@@ -16037,9 +16215,11 @@ var ChaosChainSDK = class _ChaosChainSDK {
   }
   /**
    * Check if Gateway is configured.
+   * Always returns true in v0.3.0+. Gateway is always initialized pointing to
+   * https://gateway.chaoscha.in unless overridden via gatewayConfig.
    */
   isGatewayEnabled() {
-    return this.gateway !== null;
+    return true;
   }
   /**
    * Get Gateway client instance.
@@ -16803,7 +16983,7 @@ function verifyWorkEvidence(evidence, context) {
 }
 
 // src/index.ts
-var SDK_VERSION = "0.2.4";
+var SDK_VERSION = "0.3.1";
 var ERC8004_VERSION = "1.0";
 var X402_VERSION = "1.0";
 var src_default = ChaosChainSDK;
@@ -16864,6 +17044,8 @@ exports.SDKValidationError = ValidationError;
 exports.SDK_VERSION = SDK_VERSION;
 exports.STUDIO_FACTORY_ABI = STUDIO_FACTORY_ABI;
 exports.STUDIO_PROXY_ABI = STUDIO_PROXY_ABI;
+exports.Session = Session;
+exports.SessionClient = SessionClient;
 exports.StorageError = StorageError;
 exports.StudioClient = StudioClient;
 exports.StudioManager = StudioManager;