@chaoschain/sdk 0.3.1 → 0.3.3

package/dist/index.d.ts

@@ -1,7 +1,11 @@
-import { N as NetworkConfig, I as IntegrityProof, W as WalletConfig, a as NetworkInfo, C as ContractAddresses, G as GatewayClientConfig, b as GatewayHealthResponse, c as WorkflowStatus, S as ScoreSubmissionMode, P as PendingWorkResponse, d as WorkEvidenceResponse, A as AgentRole, e as ChaosChainSDKConfig, f as AgentMetadata, g as AgentRegistration, F as FeedbackParams, h as PaymentMethod, U as UploadOptions, i as UploadResult, j as WorkflowError } from './types-BBVtx_jV.js';
-export { O as AgencySignals, o as ComputeProvider, D as DKGNodeData, R as DemoAssessment, Z as EngineeringStudioPolicy, K as EvidencePackage, k as FeedbackRecord, u as PendingWorkItem, Y as ScoreRange, $ as SignalExtractionContext, n as StorageProvider, T as TEEAttestation, p as TransactionResult, l as ValidationRequest, V as ValidationRequestParams, q as ValidationStatus, Q as VerifierAssessment, L as WorkEvidenceVerificationResult, _ as WorkMandate, M as WorkVerificationResult, t as WorkflowProgress, s as WorkflowState, r as WorkflowType, m as X402Payment, X as X402PaymentParams, v as XMTPMessageData, E as composeScoreVector, H as composeScoreVectorWithDefaults, w as computeDepth, x as derivePoAScores, B as extractAgencySignals, J as rangeFit, y as validateEvidenceGraph, z as verifyWorkEvidence } from './types-BBVtx_jV.js';
+import { N as NetworkConfig, I as IntegrityProof, W as WalletConfig, b as NetworkInfo, c as ContractAddresses, A as AgentRole, d as ChaosChainSDKConfig, e as AgentMetadata, f as AgentRegistration, F as FeedbackParams, P as PaymentMethod, U as UploadOptions, a as UploadResult, g as WorkflowStatus, h as ScoreSubmissionMode } from './types-C0Ay90UI.js';
+export { M as AgencySignals, C as ComputeProvider, D as DKGNodeData, Q as DemoAssessment, Y as EngineeringStudioPolicy, J as EvidencePackage, i as FeedbackRecord, G as GatewayClientConfig, r as PendingWorkItem, s as PendingWorkResponse, R as ScoreRange, _ as SignalExtractionContext, S as StorageProvider, T as TEEAttestation, l as TransactionResult, j as ValidationRequest, V as ValidationRequestParams, m as ValidationStatus, O as VerifierAssessment, t as WorkEvidenceResponse, K as WorkEvidenceVerificationResult, Z as WorkMandate, L as WorkVerificationResult, q as WorkflowError, p as WorkflowProgress, o as WorkflowState, n as WorkflowType, k as X402Payment, X as X402PaymentParams, u as XMTPMessageData, B as composeScoreVector, E as composeScoreVectorWithDefaults, v as computeDepth, w as derivePoAScores, z as extractAgencySignals, H as rangeFit, x as validateEvidenceGraph, y as verifyWorkEvidence } from './types-C0Ay90UI.js';
 import { ethers } from 'ethers';
-export { I as IPFSLocalStorage } from './IPFSLocal-B4hnMEfS.js';
+import { G as GatewayClient } from './index-CL0fidQs.js';
+export { A as AgentRegistrationError, C as ChaosChainSDKError, b as ConfigurationError, a as ContractError, d as GatewayConnectionError, c as GatewayError, e as GatewayTimeoutError, I as IntegrityVerificationError, P as PaymentError, V as SDKValidationError, S as StorageError, W as WorkflowFailedError } from './index-CL0fidQs.js';
+import { SessionClient } from './session/index.js';
+export { Session, SessionAgentOverride, SessionAgentRole, SessionClientConfig, SessionCompleteResult, SessionLogOptions, SessionStartOptions } from './session/index.js';
+export { I as IPFSLocalStorage } from './IPFSLocal-B_Sgmd_Q.js';
 
 /**
  * X402 Payment Manager for ChaosChain SDK
@@ -715,152 +719,6 @@ declare function getNetworkInfo(network: NetworkConfig | string): NetworkInfo;
  */
 declare function getContractAddresses(network: NetworkConfig | string): ContractAddresses;
 
-declare class GatewayClient {
-    private gatewayUrl;
-    private timeout;
-    private maxPollTime;
-    private pollInterval;
-    private defaultHeaders?;
-    private auth?;
-    private retryConfig?;
-    constructor(config: GatewayClientConfig);
-    private _resolveTimeout;
-    private _resolveAuthMode;
-    private _buildHeaders;
-    private _classifyStatusCode;
-    private _normalizeError;
-    private _getRetryDelayMs;
-    private _sleep;
-    /**
-     * Make HTTP request to Gateway.
-     * Handles errors and transforms them to Gateway exceptions.
-     */
-    private _request;
-    /**
-     * Parse workflow status from API response.
-     */
-    private _parseWorkflowStatus;
-    healthCheck(): Promise<GatewayHealthResponse>;
-    isHealthy(): Promise<boolean>;
-    /**
-     * Create a work submission workflow.
-     * POST /workflows/work-submission
-     *
-     * SDK prepares inputs; Gateway handles:
-     * - Evidence upload to Arweave
-     * - Transaction submission
-     * - Confirmation waiting
-     *
-     * @param studioAddress - Ethereum address of the studio
-     * @param epoch - Epoch number
-     * @param agentAddress - Ethereum address of the submitting agent
-     * @param dataHash - Bytes32 hash of the work (as hex string)
-     * @param threadRoot - Bytes32 DKG thread root (as hex string)
-     * @param evidenceRoot - Bytes32 evidence Merkle root (as hex string)
-     * @param evidenceContent - Raw evidence bytes (will be base64 encoded)
-     * @param signerAddress - Ethereum address of the signer (must be registered in Gateway)
-     * @returns WorkflowStatus - Initial status of the created workflow
-     */
-    submitWork(studioAddress: string, epoch: number, agentAddress: string, dataHash: string, threadRoot: string, evidenceRoot: string, evidenceContent: Buffer | string, signerAddress: string): Promise<WorkflowStatus>;
-    /**
-     * Create a score submission workflow.
-     * POST /workflows/score-submission
-     *
-     * Supports two modes:
-     * - DIRECT (default): Simple direct scoring, requires workerAddress
-     * - COMMIT_REVEAL: Commit-reveal pattern, requires salt
-     *
-     * @param studioAddress - Ethereum address of the studio
-     * @param epoch - Epoch number
-     * @param validatorAddress - Ethereum address of the validator
-     * @param dataHash - Bytes32 hash of the work being scored (as hex string)
-     * @param scores - Array of dimension scores (0-10000 basis points)
-     * @param signerAddress - Ethereum address of the signer
-     * @param options - Additional options (workerAddress, salt, mode)
-     */
-    submitScore(studioAddress: string, epoch: number, validatorAddress: string, dataHash: string, scores: number[], signerAddress: string, options?: {
-        workerAddress?: string;
-        salt?: string;
-        mode?: ScoreSubmissionMode;
-    }): Promise<WorkflowStatus>;
-    /**
-     * Create a close epoch workflow.
-     * POST /workflows/close-epoch
-     *
-     * This is economically final — cannot be undone.
-     *
-     * @param studioAddress - Ethereum address of the studio
-     * @param epoch - Epoch number to close
-     * @param signerAddress - Ethereum address of the signer
-     */
-    closeEpoch(studioAddress: string, epoch: number, signerAddress: string): Promise<WorkflowStatus>;
-    /**
-     * Get workflow status by ID.
-     * GET /workflows/{id}
-     */
-    getWorkflow(workflowId: string): Promise<WorkflowStatus>;
-    /**
-     * List workflows with optional filters.
-     * GET /workflows?studio=&state=&type=
-     */
-    listWorkflows(options?: {
-        studio?: string;
-        state?: string;
-        workflowType?: string;
-    }): Promise<WorkflowStatus[]>;
-    /**
-     * Poll workflow until it reaches a terminal state.
-     *
-     * @param workflowId - UUID of the workflow
-     * @param options - Polling options
-     * @throws WorkflowFailedError - If workflow reaches FAILED state
-     * @throws GatewayTimeoutError - If maxWait exceeded
-     */
-    waitForCompletion(workflowId: string, options?: {
-        maxWait?: number;
-        pollInterval?: number;
-        onProgress?: (status: WorkflowStatus) => void;
-    }): Promise<WorkflowStatus>;
-    /**
-     * Submit work and wait for completion.
-     */
-    submitWorkAndWait(studioAddress: string, epoch: number, agentAddress: string, dataHash: string, threadRoot: string, evidenceRoot: string, evidenceContent: Buffer | string, signerAddress: string, options?: {
-        onProgress?: (status: WorkflowStatus) => void;
-    }): Promise<WorkflowStatus>;
-    /**
-     * Submit score and wait for completion.
-     */
-    submitScoreAndWait(studioAddress: string, epoch: number, validatorAddress: string, dataHash: string, scores: number[], signerAddress: string, options?: {
-        workerAddress?: string;
-        workAddress?: string;
-        salt?: string;
-        mode?: ScoreSubmissionMode;
-        onProgress?: (status: WorkflowStatus) => void;
-    }): Promise<WorkflowStatus>;
-    /**
-     * Close epoch and wait for completion.
-     */
-    closeEpochAndWait(studioAddress: string, epoch: number, signerAddress: string, options?: {
-        onProgress?: (status: WorkflowStatus) => void;
-    }): Promise<WorkflowStatus>;
-    /**
-     * Fetch pending (unfinalized) work for a studio from the gateway.
-     *
-     * @param studioAddress - 0x-prefixed studio contract address
-     * @param options - Optional limit/offset for pagination
-     * @returns Typed pending work response
-     */
-    getPendingWork(studioAddress: string, options?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<PendingWorkResponse>;
-    /**
-     * Fetch full evidence graph for a work submission.
-     * Endpoint: GET /v1/work/{hash}/evidence
-     */
-    getWorkEvidence(workHash: string): Promise<WorkEvidenceResponse>;
-}
-
 interface StudioClientConfig {
     provider: ethers.Provider;
     signer: ethers.Signer;
@@ -1032,174 +890,6 @@ declare class StudioClient {
     generateSalt(): string;
 }
 
-/**
- * Session — high-level wrapper for ChaosChain Engineering Studio sessions.
- *
- * Agents use this class to log work events without constructing raw event schemas,
- * managing parent IDs, or thinking about DAGs. The gateway handles all of that.
- *
- * @example
- * ```ts
- * const session = await client.start({ studio_address: '0x...', agent_address: '0x...' });
- * await session.log({ summary: 'Planning cache layer implementation' });
- * await session.step('implementing', 'Added CacheService class');
- * await session.step('testing', 'All 47 tests pass');
- * const { workflow_id, data_hash } = await session.complete();
- * ```
- */
-/** Valid agent roles accepted by the gateway for session events. */
-type SessionAgentRole = 'worker' | 'verifier' | 'collaborator';
-/** Per-event agent override. */
-interface SessionAgentOverride {
-    /** Wallet address of the agent emitting this event. */
-    agent_address: string;
-    /** Agent role (defaults to `"worker"`). Must be `worker`, `verifier`, or `collaborator`. */
-    role?: SessionAgentRole;
-}
-/** Options for {@link Session.log}. */
-interface SessionLogOptions {
-    /** Human-readable description of what happened. */
-    summary: string;
-    /** Canonical event type. Defaults to `"artifact_created"`. */
-    event_type?: string;
-    /** Arbitrary metadata attached to the event. */
-    metadata?: Record<string, unknown>;
-    /** Override the session-level agent for this event. */
-    agent?: SessionAgentOverride;
-}
-/** Result returned by {@link Session.complete}. */
-interface SessionCompleteResult {
-    workflow_id: string | null;
-    data_hash: string | null;
-}
-declare class Session {
-    /** Session ID returned by the gateway. */
-    readonly sessionId: string;
-    private readonly gatewayUrl;
-    private readonly apiKey;
-    private readonly studioAddress;
-    private readonly agentAddress;
-    private readonly studioPolicyVersion;
-    private readonly workMandateId;
-    private readonly taskType;
-    private lastEventId;
-    /** @internal — use {@link SessionClient.start} to create instances. */
-    constructor(opts: {
-        sessionId: string;
-        gatewayUrl: string;
-        apiKey?: string;
-        lastEventId?: string | null;
-        studioAddress: string;
-        agentAddress: string;
-        studioPolicyVersion: string;
-        workMandateId: string;
-        taskType: string;
-    });
-    /**
-     * 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.
-     */
-    log(opts: SessionLogOptions): Promise<void>;
-    /**
-     * 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.
-     */
-    step(stepType: string, summary: string, agent?: SessionAgentOverride): Promise<void>;
-    /**
-     * 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.
-     */
-    complete(opts?: {
-        status?: 'completed' | 'failed';
-        summary?: string;
-    }): Promise<SessionCompleteResult>;
-    private post;
-}
-
-/**
- * SessionClient — factory for creating ChaosChain Engineering Studio sessions.
- *
- * @example
- * ```ts
- * import { SessionClient } from '@chaoschain/sdk';
- *
- * const client = new SessionClient({ gatewayUrl: 'https://gateway.chaoscha.in', apiKey: 'cc_...' });
- * const session = await client.start({
- *   studio_address: '0xFA0795fD5D7F58eCAa7Eae35Ad9cB8AED9424Dd0',
- *   agent_address: '0x9B4Cef62a0ce1671ccFEFA6a6D8cBFa165c49831',
- *   task_type: 'feature',
- * });
- *
- * await session.log({ summary: 'Started implementing cache layer' });
- * await session.step('testing', 'All tests pass');
- * const result = await session.complete();
- * ```
- */
-
-/** Configuration for {@link SessionClient}. */
-interface SessionClientConfig {
-    /** Gateway base URL (default: `"https://gateway.chaoscha.in"`). */
-    gatewayUrl?: string;
-    /** API key sent as `X-API-Key` header. */
-    apiKey?: string;
-}
-/** Options for {@link SessionClient.start}. */
-interface SessionStartOptions {
-    /** Studio contract address (required). */
-    studio_address: string;
-    /** Worker agent wallet address (required). */
-    agent_address: string;
-    /** Work mandate ID (default: `"generic-task"`). */
-    work_mandate_id?: string;
-    /** Task classification (default: `"general"`). */
-    task_type?: string;
-    /** Studio policy version (default: `"engineering-studio-default-v1"`). */
-    studio_policy_version?: string;
-    /** Client-provided session ID. Server generates one if omitted. */
-    session_id?: string;
-}
-declare class SessionClient {
-    private readonly gatewayUrl;
-    private readonly apiKey;
-    constructor(config?: SessionClientConfig);
-    /**
-     * 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.
-     */
-    start(opts: SessionStartOptions): Promise<Session>;
-}
-
 /**
  * Main ChaosChain SDK Class - Complete TypeScript implementation
  *
@@ -1957,80 +1647,6 @@ declare class AutoStorageManager implements StorageBackend {
     getAvailableBackends(): string[];
 }
 
-/**
- * Exception classes for the ChaosChain SDK.
- *
- * This module defines all custom exceptions used throughout the SDK
- * to provide clear error handling and debugging information.
- */
-declare class ChaosChainSDKError extends Error {
-    details: Record<string, any>;
-    constructor(message: string, details?: Record<string, any>);
-    toString(): string;
-}
-declare class AgentRegistrationError extends ChaosChainSDKError {
-    constructor(message: string, details?: Record<string, any>);
-}
-declare class PaymentError extends ChaosChainSDKError {
-    constructor(message: string, details?: Record<string, any>);
-}
-declare class StorageError extends ChaosChainSDKError {
-    constructor(message: string, details?: Record<string, any>);
-}
-declare class IntegrityVerificationError extends ChaosChainSDKError {
-    constructor(message: string, details?: Record<string, any>);
-}
-declare class ContractError extends ChaosChainSDKError {
-    constructor(message: string, details?: Record<string, any>);
-}
-declare class ValidationError extends ChaosChainSDKError {
-    constructor(message: string, details?: Record<string, any>);
-}
-declare class ConfigurationError extends ChaosChainSDKError {
-    constructor(message: string, details?: Record<string, any>);
-}
-/**
- * Options passed when constructing a GatewayError (statusCode, response, category, retryable).
- */
-interface GatewayErrorDetails {
-    statusCode?: number;
-    response?: Record<string, any>;
-    category?: 'transient' | 'permanent' | 'auth' | 'unknown';
-    retryable?: boolean;
-}
-/**
- * Base error from Gateway API.
- */
-declare class GatewayError extends ChaosChainSDKError {
-    readonly statusCode?: number;
-    readonly response?: Record<string, any>;
-    readonly category?: 'transient' | 'permanent' | 'auth' | 'unknown';
-    readonly retryable?: boolean;
-    constructor(message: string, details?: GatewayErrorDetails);
-}
-/**
- * Failed to connect to Gateway.
- */
-declare class GatewayConnectionError extends GatewayError {
-    constructor(message: string);
-}
-/**
- * Gateway request or polling timed out.
- */
-declare class GatewayTimeoutError extends GatewayError {
-    readonly workflowId: string;
-    readonly lastStatus?: WorkflowStatus;
-    constructor(workflowId: string, message: string, lastStatus?: WorkflowStatus);
-}
-/**
- * Workflow reached FAILED state.
- */
-declare class WorkflowFailedError extends GatewayError {
-    readonly workflowId: string;
-    readonly workflowError: WorkflowError;
-    constructor(workflowId: string, error: WorkflowError);
-}
-
 /**
  * ERC-8004 v1.0 Contract ABIs and Addresses
  *
@@ -2707,7 +2323,7 @@ declare class StudioManager {
  * @packageDocumentation
  */
 
-declare const SDK_VERSION = "0.3.1";
+declare const SDK_VERSION = "0.3.3";
 declare const ERC8004_VERSION = "1.0";
 declare const X402_VERSION = "1.0";
 
@@ -2744,4 +2360,4 @@ declare function initChaosChainSDK(config: {
     enableStorage?: boolean;
 }): ChaosChainSDK;
 
-export { A2AX402Extension, AgentMetadata, AgentRegistration, AgentRegistrationError, AgentRole, AutoStorageManager, CHAOS_CORE_ABI, ChaosAgent, ChaosChainSDK, ChaosChainSDKConfig, ChaosChainSDKError, ConfigurationError, ContractAddresses, ContractError, ERC8004_VERSION, FeedbackParams, GatewayClient, GatewayClientConfig, GatewayConnectionError, GatewayError, GatewayTimeoutError, GoogleAP2Integration, IDENTITY_REGISTRY_ABI, PinataStorage as IPFSPinataStorage, IntegrityProof, IntegrityVerificationError, IrysStorage, IrysStorage as IrysStorageProvider, LocalIPFSStorage, MandateManager, NetworkConfig, PaymentError, type PaymentHeader, PaymentManager, PaymentMethod, PendingWorkResponse, PinataStorage, REPUTATION_REGISTRY_ABI, REWARDS_DISTRIBUTOR_ABI, ValidationError as SDKValidationError, SDK_VERSION, STUDIO_FACTORY_ABI, STUDIO_PROXY_ABI, Session, type SessionAgentOverride, type SessionAgentRole, SessionClient, type SessionClientConfig, type SessionCompleteResult, type SessionLogOptions, type SessionStartOptions, type SettleRequest, type SettleResponse, type StorageBackend, StorageError, type StorageResult, StudioClient, type StudioClientConfig, StudioManager, type StudioManagerConfig, type Task, type TransferAuthorizationParams, UploadOptions, UploadResult, VALIDATION_REGISTRY_ABI, WalletConfig, WalletManager, WorkEvidenceResponse, type WorkerBid, WorkflowError, WorkflowFailedError, WorkflowStatus, type X402FacilitatorConfig, X402PaymentManager, type X402PaymentProof, type X402PaymentRequest$1 as X402PaymentRequest, type X402PaymentRequirements, X402Server, X402_VERSION, ZeroGStorage, ChaosChainSDK as default, getContractAddresses, getNetworkInfo, initChaosChainSDK };
+export { A2AX402Extension, AgentMetadata, AgentRegistration, AgentRole, AutoStorageManager, CHAOS_CORE_ABI, ChaosAgent, ChaosChainSDK, ChaosChainSDKConfig, ContractAddresses, ERC8004_VERSION, FeedbackParams, GatewayClient, GoogleAP2Integration, IDENTITY_REGISTRY_ABI, PinataStorage as IPFSPinataStorage, IntegrityProof, IrysStorage, IrysStorage as IrysStorageProvider, LocalIPFSStorage, MandateManager, NetworkConfig, type PaymentHeader, PaymentManager, PaymentMethod, PinataStorage, REPUTATION_REGISTRY_ABI, REWARDS_DISTRIBUTOR_ABI, SDK_VERSION, STUDIO_FACTORY_ABI, STUDIO_PROXY_ABI, SessionClient, type SettleRequest, type SettleResponse, type StorageBackend, type StorageResult, StudioClient, type StudioClientConfig, StudioManager, type StudioManagerConfig, type Task, type TransferAuthorizationParams, UploadOptions, UploadResult, VALIDATION_REGISTRY_ABI, WalletConfig, WalletManager, type WorkerBid, WorkflowStatus, type X402FacilitatorConfig, X402PaymentManager, type X402PaymentProof, type X402PaymentRequest$1 as X402PaymentRequest, type X402PaymentRequirements, X402Server, X402_VERSION, ZeroGStorage, ChaosChainSDK as default, getContractAddresses, getNetworkInfo, initChaosChainSDK };

package/dist/index.js

@@ -15375,10 +15375,16 @@ var STEP_TYPE_MAP = {
 var Session = class {
   /** Session ID returned by the gateway. */
   sessionId;
-  gatewayUrl;
-  apiKey;
+  /** Epoch number returned by the gateway. */
+  epoch;
+  /** Studio contract address for this session. */
   studioAddress;
+  /** Default agent wallet address for this session. */
   agentAddress;
+  /** URL to view this session's Evidence DAG in the browser. */
+  viewerUrl;
+  gatewayUrl;
+  apiKey;
   studioPolicyVersion;
   workMandateId;
   taskType;
@@ -15386,6 +15392,8 @@ var Session = class {
   /** @internal — use {@link SessionClient.start} to create instances. */
   constructor(opts) {
     this.sessionId = opts.sessionId;
+    this.epoch = opts.epoch;
+    this.viewerUrl = `${opts.gatewayUrl}/v1/sessions/${opts.sessionId}/viewer`;
     this.gatewayUrl = opts.gatewayUrl;
     this.apiKey = opts.apiKey;
     this.lastEventId = opts.lastEventId ?? null;
@@ -15401,7 +15409,12 @@ var Session = class {
    * 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.
+   * @param opts.summary - Human-readable description of what happened (required).
+   * @param opts.event_type - Canonical event type (default: `"artifact_created"`).
+   * @param opts.metadata - Arbitrary key-value metadata attached to the event.
+   * @param opts.agent - Override the session-level agent for this event.
+   *   Pass `{ agent_address, role? }` to emit the event from a different agent.
+   *   Valid roles: `"worker"`, `"verifier"`, `"collaborator"`. Defaults to `"worker"`.
    * @throws Error if the gateway returns a non-2xx status.
    */
   async log(opts) {
@@ -15444,8 +15457,9 @@ var Session = class {
    *
    * Unknown step types fall back to `artifact_created`.
    *
-   * @param stepType - Friendly step name.
+   * @param stepType - Friendly step name (`"planning"`, `"implementing"`, `"testing"`, `"debugging"`, `"completing"`).
    * @param summary - What happened in this step.
+   * @param agent - Optional agent override for this event. Same as `log({ agent })`.
    */
   async step(stepType, summary, agent) {
     const eventType = STEP_TYPE_MAP[stepType] ?? "artifact_created";
@@ -15455,11 +15469,13 @@ var Session = class {
    * 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.
+   * and returns the session result.
    *
-   * @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.
+   * @param opts.status - `"completed"` or `"failed"` (default: `"completed"`).
+   * @param opts.summary - Human-readable summary of the session outcome.
+   * @returns `{ workflow_id, data_hash, epoch }` — `workflow_id` and `data_hash`
+   *          may be `null` if the gateway workflow engine is not configured.
+   *          `epoch` is the epoch this session belongs to.
    * @throws Error if the gateway returns a non-2xx status.
    */
   async complete(opts) {
@@ -15469,7 +15485,8 @@ var Session = class {
     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
+      data_hash: data.data?.data_hash ?? null,
+      epoch: data.data.epoch
     };
   }
   // ---------------------------------------------------------------------------
@@ -15506,8 +15523,16 @@ var SessionClient = class {
    * 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.
+   * The returned session exposes `session.sessionId`, `session.epoch`,
+   * `session.studioAddress`, and `session.agentAddress`.
+   *
+   * @param opts.studio_address - Studio contract address (required).
+   * @param opts.agent_address - Worker agent wallet address (required).
+   * @param opts.task_type - Task classification: `"feature"`, `"bugfix"`, `"refactor"`, etc. (default: `"general"`).
+   * @param opts.work_mandate_id - Work mandate identifier (default: `"generic-task"`).
+   * @param opts.studio_policy_version - Studio policy version (default: `"engineering-studio-default-v1"`).
+   * @param opts.session_id - Client-provided session ID. Server generates one if omitted.
+   * @returns A live {@link Session} bound to the newly created session ID and epoch.
    * @throws Error if the gateway returns a non-2xx status.
    */
   async start(opts) {
@@ -15544,7 +15569,8 @@ var SessionClient = class {
       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"
+      taskType: opts.task_type ?? "general",
+      epoch: data.data.epoch
     });
   }
 };
@@ -16157,7 +16183,7 @@ var ChaosChainSDK = class _ChaosChainSDK {
    * Get SDK version
    */
   getVersion() {
-    return "0.3.1";
+    return "0.3.3";
   }
   /**
    * Get SDK capabilities summary
@@ -16955,7 +16981,7 @@ function verifyWorkEvidence(evidence, context) {
 }
 
 // src/index.ts
-var SDK_VERSION = "0.3.1";
+var SDK_VERSION = "0.3.3";
 var ERC8004_VERSION = "1.0";
 var X402_VERSION = "1.0";
 var src_default = ChaosChainSDK;