@chaoschain/sdk 0.3.2 → 0.3.3

package/dist/session/index.cjs

@@ -18,10 +18,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;
@@ -29,6 +35,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;
@@ -44,7 +52,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) {
@@ -87,8 +100,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";
@@ -98,11 +112,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) {
@@ -112,7 +128,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
     };
   }
   // ---------------------------------------------------------------------------
@@ -147,8 +164,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) {
@@ -185,7 +210,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
     });
   }
 };

package/dist/session/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/session/Session.ts","../../src/session/SessionClient.ts"],"names":["randomUUID","axios"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Session — high-level wrapper for ChaosChain Engineering Studio sessions.\n *\n * Agents use this class to log work events without constructing raw event schemas,\n * managing parent IDs, or thinking about DAGs. The gateway handles all of that.\n *\n * @example\n * ```ts\n * const session = await client.start({ studio_address: '0x...', agent_address: '0x...' });\n * await session.log({ summary: 'Planning cache layer implementation' });\n * await session.step('implementing', 'Added CacheService class');\n * await session.step('testing', 'All 47 tests pass');\n * const { workflow_id, data_hash } = await session.complete();\n * ```\n */\n\nimport { randomUUID } from 'node:crypto';\nimport axios, { AxiosError } from 'axios';\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/** Valid agent roles accepted by the gateway for session events. */\nexport type SessionAgentRole = 'worker' | 'verifier' | 'collaborator';\n\n/** Per-event agent override. */\nexport interface SessionAgentOverride {\n  /** Wallet address of the agent emitting this event. */\n  agent_address: string;\n  /** Agent role (defaults to `\"worker\"`). Must be `worker`, `verifier`, or `collaborator`. */\n  role?: SessionAgentRole;\n}\n\n/** Options for {@link Session.log}. */\nexport interface SessionLogOptions {\n  /** Human-readable description of what happened. */\n  summary: string;\n  /** Canonical event type. Defaults to `\"artifact_created\"`. */\n  event_type?: string;\n  /** Arbitrary metadata attached to the event. */\n  metadata?: Record<string, unknown>;\n  /** Override the session-level agent for this event. */\n  agent?: SessionAgentOverride;\n}\n\n/** Result returned by {@link Session.complete}. */\nexport interface SessionCompleteResult {\n  workflow_id: string | null;\n  data_hash: string | null;\n}\n\n/** Canonical event-type mappings for {@link Session.step}. */\nconst STEP_TYPE_MAP: Record<string, string> = {\n  planning: 'plan_created',\n  testing: 'test_run',\n  debugging: 'debug_step',\n  implementing: 'file_written',\n  completing: 'submission_created',\n};\n\n// =============================================================================\n// Session\n// =============================================================================\n\nexport class Session {\n  /** Session ID returned by the gateway. */\n  public readonly sessionId: string;\n\n  private readonly gatewayUrl: string;\n  private readonly apiKey: string | undefined;\n  private readonly studioAddress: string;\n  private readonly agentAddress: string;\n  private readonly studioPolicyVersion: string;\n  private readonly workMandateId: string;\n  private readonly taskType: string;\n  private lastEventId: string | null;\n\n  /** @internal — use {@link SessionClient.start} to create instances. */\n  constructor(opts: {\n    sessionId: string;\n    gatewayUrl: string;\n    apiKey?: string;\n    lastEventId?: string | null;\n    studioAddress: string;\n    agentAddress: string;\n    studioPolicyVersion: string;\n    workMandateId: string;\n    taskType: string;\n  }) {\n    this.sessionId = opts.sessionId;\n    this.gatewayUrl = opts.gatewayUrl;\n    this.apiKey = opts.apiKey;\n    this.lastEventId = opts.lastEventId ?? null;\n    this.studioAddress = opts.studioAddress;\n    this.agentAddress = opts.agentAddress;\n    this.studioPolicyVersion = opts.studioPolicyVersion;\n    this.workMandateId = opts.workMandateId;\n    this.taskType = opts.taskType;\n  }\n\n  /**\n   * Log a session event.\n   *\n   * Automatically generates `event_id`, `timestamp`, and chains `parent_event_ids`\n   * from the previous event so the gateway can build a causal DAG.\n   *\n   * @param opts - Event details. Only `summary` is required.\n   * @throws Error if the gateway returns a non-2xx status.\n   */\n  async log(opts: SessionLogOptions): Promise<void> {\n    const eventId = randomUUID();\n    const event = {\n      event_id: eventId,\n      event_type: opts.event_type ?? 'artifact_created',\n      timestamp: new Date().toISOString(),\n      summary: opts.summary,\n      causality: {\n        parent_event_ids: this.lastEventId ? [this.lastEventId] : [],\n      },\n      agent: {\n        agent_address: opts.agent?.agent_address ?? this.agentAddress,\n        role: opts.agent?.role ?? 'worker',\n      },\n      studio: {\n        studio_address: this.studioAddress,\n        studio_policy_version: this.studioPolicyVersion,\n      },\n      task: {\n        work_mandate_id: this.workMandateId,\n        task_type: this.taskType,\n      },\n      ...(opts.metadata ? { metadata: opts.metadata } : {}),\n    };\n\n    await this.post(`/v1/sessions/${this.sessionId}/events`, [event]);\n    this.lastEventId = eventId;\n  }\n\n  /**\n   * Convenience wrapper around {@link log} that maps human-friendly step names\n   * to canonical event types.\n   *\n   * Mappings:\n   * - `\"planning\"` → `plan_created`\n   * - `\"testing\"` → `test_run`\n   * - `\"debugging\"` → `debug_step`\n   * - `\"implementing\"` → `file_written`\n   * - `\"completing\"` → `submission_created`\n   *\n   * Unknown step types fall back to `artifact_created`.\n   *\n   * @param stepType - Friendly step name.\n   * @param summary - What happened in this step.\n   */\n  async step(stepType: string, summary: string, agent?: SessionAgentOverride): Promise<void> {\n    const eventType = STEP_TYPE_MAP[stepType] ?? 'artifact_created';\n    await this.log({ event_type: eventType, summary, agent });\n  }\n\n  /**\n   * Complete the session.\n   *\n   * Triggers the on-chain WorkSubmission workflow (if the gateway is configured for it)\n   * and returns `workflow_id` + `data_hash` for downstream verification/scoring.\n   *\n   * @param opts - Optional status (`\"completed\"` | `\"failed\"`) and summary.\n   * @returns `{ workflow_id, data_hash }` — both may be `null` if the gateway\n   *          workflow engine is not configured.\n   * @throws Error if the gateway returns a non-2xx status.\n   */\n  async complete(\n    opts?: { status?: 'completed' | 'failed'; summary?: string },\n  ): Promise<SessionCompleteResult> {\n    const body: Record<string, unknown> = {};\n    if (opts?.status) body.status = opts.status;\n    if (opts?.summary) body.summary = opts.summary;\n\n    const data = await this.post<{\n      data: { workflow_id: string | null; data_hash: string | null };\n    }>(`/v1/sessions/${this.sessionId}/complete`, body);\n\n    return {\n      workflow_id: data.data?.workflow_id ?? null,\n      data_hash: data.data?.data_hash ?? null,\n    };\n  }\n\n  // ---------------------------------------------------------------------------\n  // Internal HTTP helper\n  // ---------------------------------------------------------------------------\n\n  private async post<T = unknown>(path: string, body: unknown): Promise<T> {\n    const url = `${this.gatewayUrl}${path}`;\n    const headers: Record<string, string> = { 'Content-Type': 'application/json' };\n    if (this.apiKey) headers['X-API-Key'] = this.apiKey;\n\n    try {\n      const res = await axios({ method: 'POST', url, data: body, headers, timeout: 30_000 });\n      return res.data as T;\n    } catch (err) {\n      const axiosErr = err as AxiosError;\n      const status = axiosErr.response?.status ?? 0;\n      const detail = JSON.stringify(axiosErr.response?.data ?? axiosErr.message);\n      throw new Error(`Session request failed: POST ${path} → ${status} ${detail}`);\n    }\n  }\n}\n","/**\n * SessionClient — factory for creating ChaosChain Engineering Studio sessions.\n *\n * @example\n * ```ts\n * import { SessionClient } from '@chaoschain/sdk';\n *\n * const client = new SessionClient({ gatewayUrl: 'https://gateway.chaoscha.in', apiKey: 'cc_...' });\n * const session = await client.start({\n *   studio_address: '0xFA0795fD5D7F58eCAa7Eae35Ad9cB8AED9424Dd0',\n *   agent_address: '0x9B4Cef62a0ce1671ccFEFA6a6D8cBFa165c49831',\n *   task_type: 'feature',\n * });\n *\n * await session.log({ summary: 'Started implementing cache layer' });\n * await session.step('testing', 'All tests pass');\n * const result = await session.complete();\n * ```\n */\n\nimport axios, { AxiosError } from 'axios';\nimport { Session } from './Session';\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/** Configuration for {@link SessionClient}. */\nexport interface SessionClientConfig {\n  /** Gateway base URL (default: `\"https://gateway.chaoscha.in\"`). */\n  gatewayUrl?: string;\n  /** API key sent as `X-API-Key` header. */\n  apiKey?: string;\n}\n\n/** Options for {@link SessionClient.start}. */\nexport interface SessionStartOptions {\n  /** Studio contract address (required). */\n  studio_address: string;\n  /** Worker agent wallet address (required). */\n  agent_address: string;\n  /** Work mandate ID (default: `\"generic-task\"`). */\n  work_mandate_id?: string;\n  /** Task classification (default: `\"general\"`). */\n  task_type?: string;\n  /** Studio policy version (default: `\"engineering-studio-default-v1\"`). */\n  studio_policy_version?: string;\n  /** Client-provided session ID. Server generates one if omitted. */\n  session_id?: string;\n}\n\n// =============================================================================\n// SessionClient\n// =============================================================================\n\nexport class SessionClient {\n  private readonly gatewayUrl: string;\n  private readonly apiKey: string | undefined;\n\n  constructor(config: SessionClientConfig = {}) {\n    this.gatewayUrl = (config.gatewayUrl ?? 'https://gateway.chaoscha.in').replace(/\\/$/, '');\n    this.apiKey = config.apiKey;\n  }\n\n  /**\n   * Create a new coding session on the gateway.\n   *\n   * Returns a {@link Session} instance that can be used to log events, run steps,\n   * and complete the session. The gateway persists all events and constructs the\n   * Evidence DAG automatically.\n   *\n   * @param opts - Session creation parameters.\n   * @returns A live {@link Session} bound to the newly created session ID.\n   * @throws Error if the gateway returns a non-2xx status.\n   */\n  async start(opts: SessionStartOptions): Promise<Session> {\n    const body: Record<string, string> = {\n      studio_address: opts.studio_address,\n      agent_address: opts.agent_address,\n    };\n    if (opts.work_mandate_id) body.work_mandate_id = opts.work_mandate_id;\n    if (opts.task_type) body.task_type = opts.task_type;\n    if (opts.studio_policy_version) body.studio_policy_version = opts.studio_policy_version;\n    if (opts.session_id) body.session_id = opts.session_id;\n\n    const url = `${this.gatewayUrl}/v1/sessions`;\n    const headers: Record<string, string> = { 'Content-Type': 'application/json' };\n    if (this.apiKey) headers['X-API-Key'] = this.apiKey;\n\n    let data: { data: { session_id: string } };\n    try {\n      const res = await axios({ method: 'POST', url, data: body, headers, timeout: 30_000 });\n      data = res.data as typeof data;\n    } catch (err) {\n      const axiosErr = err as AxiosError;\n      const status = axiosErr.response?.status ?? 0;\n      const detail = JSON.stringify(axiosErr.response?.data ?? axiosErr.message);\n      throw new Error(`Failed to create session: POST /v1/sessions → ${status} ${detail}`);\n    }\n\n    const sessionId = data.data?.session_id;\n    if (!sessionId) {\n      throw new Error('Gateway response missing session_id');\n    }\n\n    return new Session({\n      sessionId,\n      gatewayUrl: this.gatewayUrl,\n      apiKey: this.apiKey,\n      studioAddress: opts.studio_address,\n      agentAddress: opts.agent_address,\n      studioPolicyVersion: opts.studio_policy_version ?? 'engineering-studio-default-v1',\n      workMandateId: opts.work_mandate_id ?? 'generic-task',\n      taskType: opts.task_type ?? 'general',\n    });\n  }\n}\n"]}
+{"version":3,"sources":["../../src/session/Session.ts","../../src/session/SessionClient.ts"],"names":["randomUUID","axios"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Session — high-level wrapper for ChaosChain Engineering Studio sessions.\n *\n * Agents use this class to log work events without constructing raw event schemas,\n * managing parent IDs, or thinking about DAGs. The gateway handles all of that.\n *\n * @example\n * ```ts\n * const session = await client.start({ studio_address: '0x...', agent_address: '0x...' });\n * await session.log({ summary: 'Planning cache layer implementation' });\n * await session.step('implementing', 'Added CacheService class');\n * await session.step('testing', 'All 47 tests pass');\n * const { workflow_id, data_hash } = await session.complete();\n * ```\n */\n\nimport { randomUUID } from 'node:crypto';\nimport axios, { AxiosError } from 'axios';\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/** Valid agent roles accepted by the gateway for session events. */\nexport type SessionAgentRole = 'worker' | 'verifier' | 'collaborator';\n\n/** Per-event agent override. */\nexport interface SessionAgentOverride {\n  /** Wallet address of the agent emitting this event. */\n  agent_address: string;\n  /** Agent role (defaults to `\"worker\"`). Must be `worker`, `verifier`, or `collaborator`. */\n  role?: SessionAgentRole;\n}\n\n/** Options for {@link Session.log}. */\nexport interface SessionLogOptions {\n  /** Human-readable description of what happened. */\n  summary: string;\n  /** Canonical event type. Defaults to `\"artifact_created\"`. */\n  event_type?: string;\n  /** Arbitrary metadata attached to the event. */\n  metadata?: Record<string, unknown>;\n  /** Override the session-level agent for this event. */\n  agent?: SessionAgentOverride;\n}\n\n/** Result returned by {@link Session.complete}. */\nexport interface SessionCompleteResult {\n  workflow_id: string | null;\n  data_hash: string | null;\n  epoch: number;\n}\n\n/** Canonical event-type mappings for {@link Session.step}. */\nconst STEP_TYPE_MAP: Record<string, string> = {\n  planning: 'plan_created',\n  testing: 'test_run',\n  debugging: 'debug_step',\n  implementing: 'file_written',\n  completing: 'submission_created',\n};\n\n// =============================================================================\n// Session\n// =============================================================================\n\nexport class Session {\n  /** Session ID returned by the gateway. */\n  public readonly sessionId: string;\n  /** Epoch number returned by the gateway. */\n  public readonly epoch: number;\n  /** Studio contract address for this session. */\n  public readonly studioAddress: string;\n  /** Default agent wallet address for this session. */\n  public readonly agentAddress: string;\n  /** URL to view this session's Evidence DAG in the browser. */\n  public readonly viewerUrl: string;\n\n  private readonly gatewayUrl: string;\n  private readonly apiKey: string | undefined;\n  private readonly studioPolicyVersion: string;\n  private readonly workMandateId: string;\n  private readonly taskType: string;\n  private lastEventId: string | null;\n\n  /** @internal — use {@link SessionClient.start} to create instances. */\n  constructor(opts: {\n    sessionId: string;\n    gatewayUrl: string;\n    apiKey?: string;\n    lastEventId?: string | null;\n    studioAddress: string;\n    agentAddress: string;\n    studioPolicyVersion: string;\n    workMandateId: string;\n    taskType: string;\n    epoch: number;\n  }) {\n    this.sessionId = opts.sessionId;\n    this.epoch = opts.epoch;\n    this.viewerUrl = `${opts.gatewayUrl}/v1/sessions/${opts.sessionId}/viewer`;\n    this.gatewayUrl = opts.gatewayUrl;\n    this.apiKey = opts.apiKey;\n    this.lastEventId = opts.lastEventId ?? null;\n    this.studioAddress = opts.studioAddress;\n    this.agentAddress = opts.agentAddress;\n    this.studioPolicyVersion = opts.studioPolicyVersion;\n    this.workMandateId = opts.workMandateId;\n    this.taskType = opts.taskType;\n  }\n\n  /**\n   * Log a session event.\n   *\n   * Automatically generates `event_id`, `timestamp`, and chains `parent_event_ids`\n   * from the previous event so the gateway can build a causal DAG.\n   *\n   * @param opts.summary - Human-readable description of what happened (required).\n   * @param opts.event_type - Canonical event type (default: `\"artifact_created\"`).\n   * @param opts.metadata - Arbitrary key-value metadata attached to the event.\n   * @param opts.agent - Override the session-level agent for this event.\n   *   Pass `{ agent_address, role? }` to emit the event from a different agent.\n   *   Valid roles: `\"worker\"`, `\"verifier\"`, `\"collaborator\"`. Defaults to `\"worker\"`.\n   * @throws Error if the gateway returns a non-2xx status.\n   */\n  async log(opts: SessionLogOptions): Promise<void> {\n    const eventId = randomUUID();\n    const event = {\n      event_id: eventId,\n      event_type: opts.event_type ?? 'artifact_created',\n      timestamp: new Date().toISOString(),\n      summary: opts.summary,\n      causality: {\n        parent_event_ids: this.lastEventId ? [this.lastEventId] : [],\n      },\n      agent: {\n        agent_address: opts.agent?.agent_address ?? this.agentAddress,\n        role: opts.agent?.role ?? 'worker',\n      },\n      studio: {\n        studio_address: this.studioAddress,\n        studio_policy_version: this.studioPolicyVersion,\n      },\n      task: {\n        work_mandate_id: this.workMandateId,\n        task_type: this.taskType,\n      },\n      ...(opts.metadata ? { metadata: opts.metadata } : {}),\n    };\n\n    await this.post(`/v1/sessions/${this.sessionId}/events`, [event]);\n    this.lastEventId = eventId;\n  }\n\n  /**\n   * Convenience wrapper around {@link log} that maps human-friendly step names\n   * to canonical event types.\n   *\n   * Mappings:\n   * - `\"planning\"` → `plan_created`\n   * - `\"testing\"` → `test_run`\n   * - `\"debugging\"` → `debug_step`\n   * - `\"implementing\"` → `file_written`\n   * - `\"completing\"` → `submission_created`\n   *\n   * Unknown step types fall back to `artifact_created`.\n   *\n   * @param stepType - Friendly step name (`\"planning\"`, `\"implementing\"`, `\"testing\"`, `\"debugging\"`, `\"completing\"`).\n   * @param summary - What happened in this step.\n   * @param agent - Optional agent override for this event. Same as `log({ agent })`.\n   */\n  async step(stepType: string, summary: string, agent?: SessionAgentOverride): Promise<void> {\n    const eventType = STEP_TYPE_MAP[stepType] ?? 'artifact_created';\n    await this.log({ event_type: eventType, summary, agent });\n  }\n\n  /**\n   * Complete the session.\n   *\n   * Triggers the on-chain WorkSubmission workflow (if the gateway is configured for it)\n   * and returns the session result.\n   *\n   * @param opts.status - `\"completed\"` or `\"failed\"` (default: `\"completed\"`).\n   * @param opts.summary - Human-readable summary of the session outcome.\n   * @returns `{ workflow_id, data_hash, epoch }` — `workflow_id` and `data_hash`\n   *          may be `null` if the gateway workflow engine is not configured.\n   *          `epoch` is the epoch this session belongs to.\n   * @throws Error if the gateway returns a non-2xx status.\n   */\n  async complete(\n    opts?: { status?: 'completed' | 'failed'; summary?: string },\n  ): Promise<SessionCompleteResult> {\n    const body: Record<string, unknown> = {};\n    if (opts?.status) body.status = opts.status;\n    if (opts?.summary) body.summary = opts.summary;\n\n    const data = await this.post<{\n      data: { workflow_id: string | null; data_hash: string | null; epoch: number };\n    }>(`/v1/sessions/${this.sessionId}/complete`, body);\n\n    return {\n      workflow_id: data.data?.workflow_id ?? null,\n      data_hash: data.data?.data_hash ?? null,\n      epoch: data.data.epoch,\n    };\n  }\n\n  // ---------------------------------------------------------------------------\n  // Internal HTTP helper\n  // ---------------------------------------------------------------------------\n\n  private async post<T = unknown>(path: string, body: unknown): Promise<T> {\n    const url = `${this.gatewayUrl}${path}`;\n    const headers: Record<string, string> = { 'Content-Type': 'application/json' };\n    if (this.apiKey) headers['X-API-Key'] = this.apiKey;\n\n    try {\n      const res = await axios({ method: 'POST', url, data: body, headers, timeout: 30_000 });\n      return res.data as T;\n    } catch (err) {\n      const axiosErr = err as AxiosError;\n      const status = axiosErr.response?.status ?? 0;\n      const detail = JSON.stringify(axiosErr.response?.data ?? axiosErr.message);\n      throw new Error(`Session request failed: POST ${path} → ${status} ${detail}`);\n    }\n  }\n}\n","/**\n * SessionClient — factory for creating ChaosChain Engineering Studio sessions.\n *\n * @example\n * ```ts\n * import { SessionClient } from '@chaoschain/sdk';\n *\n * const client = new SessionClient({ gatewayUrl: 'https://gateway.chaoscha.in', apiKey: 'cc_...' });\n * const session = await client.start({\n *   studio_address: '0xFA0795fD5D7F58eCAa7Eae35Ad9cB8AED9424Dd0',\n *   agent_address: '0x9B4Cef62a0ce1671ccFEFA6a6D8cBFa165c49831',\n *   task_type: 'feature',\n * });\n *\n * await session.log({ summary: 'Started implementing cache layer' });\n * await session.step('testing', 'All tests pass');\n * const result = await session.complete();\n * ```\n */\n\nimport axios, { AxiosError } from 'axios';\nimport { Session } from './Session';\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/** Configuration for {@link SessionClient}. */\nexport interface SessionClientConfig {\n  /** Gateway base URL (default: `\"https://gateway.chaoscha.in\"`). */\n  gatewayUrl?: string;\n  /** API key sent as `X-API-Key` header. */\n  apiKey?: string;\n}\n\n/** Options for {@link SessionClient.start}. */\nexport interface SessionStartOptions {\n  /** Studio contract address (required). */\n  studio_address: string;\n  /** Worker agent wallet address (required). */\n  agent_address: string;\n  /** Work mandate ID (default: `\"generic-task\"`). */\n  work_mandate_id?: string;\n  /** Task classification (default: `\"general\"`). */\n  task_type?: string;\n  /** Studio policy version (default: `\"engineering-studio-default-v1\"`). */\n  studio_policy_version?: string;\n  /** Client-provided session ID. Server generates one if omitted. */\n  session_id?: string;\n}\n\n// =============================================================================\n// SessionClient\n// =============================================================================\n\nexport class SessionClient {\n  private readonly gatewayUrl: string;\n  private readonly apiKey: string | undefined;\n\n  constructor(config: SessionClientConfig = {}) {\n    this.gatewayUrl = (config.gatewayUrl ?? 'https://gateway.chaoscha.in').replace(/\\/$/, '');\n    this.apiKey = config.apiKey;\n  }\n\n  /**\n   * Create a new coding session on the gateway.\n   *\n   * Returns a {@link Session} instance that can be used to log events, run steps,\n   * and complete the session. The gateway persists all events and constructs the\n   * Evidence DAG automatically.\n   *\n   * The returned session exposes `session.sessionId`, `session.epoch`,\n   * `session.studioAddress`, and `session.agentAddress`.\n   *\n   * @param opts.studio_address - Studio contract address (required).\n   * @param opts.agent_address - Worker agent wallet address (required).\n   * @param opts.task_type - Task classification: `\"feature\"`, `\"bugfix\"`, `\"refactor\"`, etc. (default: `\"general\"`).\n   * @param opts.work_mandate_id - Work mandate identifier (default: `\"generic-task\"`).\n   * @param opts.studio_policy_version - Studio policy version (default: `\"engineering-studio-default-v1\"`).\n   * @param opts.session_id - Client-provided session ID. Server generates one if omitted.\n   * @returns A live {@link Session} bound to the newly created session ID and epoch.\n   * @throws Error if the gateway returns a non-2xx status.\n   */\n  async start(opts: SessionStartOptions): Promise<Session> {\n    const body: Record<string, string> = {\n      studio_address: opts.studio_address,\n      agent_address: opts.agent_address,\n    };\n    if (opts.work_mandate_id) body.work_mandate_id = opts.work_mandate_id;\n    if (opts.task_type) body.task_type = opts.task_type;\n    if (opts.studio_policy_version) body.studio_policy_version = opts.studio_policy_version;\n    if (opts.session_id) body.session_id = opts.session_id;\n\n    const url = `${this.gatewayUrl}/v1/sessions`;\n    const headers: Record<string, string> = { 'Content-Type': 'application/json' };\n    if (this.apiKey) headers['X-API-Key'] = this.apiKey;\n\n    let data: { data: { session_id: string; epoch: number } };\n    try {\n      const res = await axios({ method: 'POST', url, data: body, headers, timeout: 30_000 });\n      data = res.data as typeof data;\n    } catch (err) {\n      const axiosErr = err as AxiosError;\n      const status = axiosErr.response?.status ?? 0;\n      const detail = JSON.stringify(axiosErr.response?.data ?? axiosErr.message);\n      throw new Error(`Failed to create session: POST /v1/sessions → ${status} ${detail}`);\n    }\n\n    const sessionId = data.data?.session_id;\n    if (!sessionId) {\n      throw new Error('Gateway response missing session_id');\n    }\n\n    return new Session({\n      sessionId,\n      gatewayUrl: this.gatewayUrl,\n      apiKey: this.apiKey,\n      studioAddress: opts.studio_address,\n      agentAddress: opts.agent_address,\n      studioPolicyVersion: opts.studio_policy_version ?? 'engineering-studio-default-v1',\n      workMandateId: opts.work_mandate_id ?? 'generic-task',\n      taskType: opts.task_type ?? 'general',\n      epoch: data.data.epoch,\n    });\n  }\n}\n"]}

package/dist/session/index.d.cts

@@ -37,14 +37,21 @@ interface SessionLogOptions {
 interface SessionCompleteResult {
     workflow_id: string | null;
     data_hash: string | null;
+    epoch: number;
 }
 declare class Session {
     /** Session ID returned by the gateway. */
     readonly sessionId: string;
+    /** Epoch number returned by the gateway. */
+    readonly epoch: number;
+    /** Studio contract address for this session. */
+    readonly studioAddress: string;
+    /** Default agent wallet address for this session. */
+    readonly agentAddress: string;
+    /** URL to view this session's Evidence DAG in the browser. */
+    readonly viewerUrl: string;
     private readonly gatewayUrl;
     private readonly apiKey;
-    private readonly studioAddress;
-    private readonly agentAddress;
     private readonly studioPolicyVersion;
     private readonly workMandateId;
     private readonly taskType;
@@ -60,6 +67,7 @@ declare class Session {
         studioPolicyVersion: string;
         workMandateId: string;
         taskType: string;
+        epoch: number;
     });
     /**
      * Log a session event.
@@ -67,7 +75,12 @@ declare class Session {
      * 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.
      */
     log(opts: SessionLogOptions): Promise<void>;
@@ -84,19 +97,22 @@ declare class Session {
      *
      * 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 })`.
      */
     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.
+     * 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.
      */
     complete(opts?: {
@@ -159,8 +175,16 @@ declare class SessionClient {
      * 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.
      */
     start(opts: SessionStartOptions): Promise<Session>;

package/dist/session/index.d.ts

@@ -37,14 +37,21 @@ interface SessionLogOptions {
 interface SessionCompleteResult {
     workflow_id: string | null;
     data_hash: string | null;
+    epoch: number;
 }
 declare class Session {
     /** Session ID returned by the gateway. */
     readonly sessionId: string;
+    /** Epoch number returned by the gateway. */
+    readonly epoch: number;
+    /** Studio contract address for this session. */
+    readonly studioAddress: string;
+    /** Default agent wallet address for this session. */
+    readonly agentAddress: string;
+    /** URL to view this session's Evidence DAG in the browser. */
+    readonly viewerUrl: string;
     private readonly gatewayUrl;
     private readonly apiKey;
-    private readonly studioAddress;
-    private readonly agentAddress;
     private readonly studioPolicyVersion;
     private readonly workMandateId;
     private readonly taskType;
@@ -60,6 +67,7 @@ declare class Session {
         studioPolicyVersion: string;
         workMandateId: string;
         taskType: string;
+        epoch: number;
     });
     /**
      * Log a session event.
@@ -67,7 +75,12 @@ declare class Session {
      * 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.
      */
     log(opts: SessionLogOptions): Promise<void>;
@@ -84,19 +97,22 @@ declare class Session {
      *
      * 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 })`.
      */
     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.
+     * 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.
      */
     complete(opts?: {
@@ -159,8 +175,16 @@ declare class SessionClient {
      * 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.
      */
     start(opts: SessionStartOptions): Promise<Session>;

package/dist/session/index.js

@@ -12,10 +12,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;
@@ -23,6 +29,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;
@@ -38,7 +46,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) {
@@ -81,8 +94,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";
@@ -92,11 +106,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) {
@@ -106,7 +122,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
     };
   }
   // ---------------------------------------------------------------------------
@@ -141,8 +158,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) {
@@ -179,7 +204,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
     });
   }
 };

package/dist/session/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/session/Session.ts","../../src/session/SessionClient.ts"],"names":["axios"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Session — high-level wrapper for ChaosChain Engineering Studio sessions.\n *\n * Agents use this class to log work events without constructing raw event schemas,\n * managing parent IDs, or thinking about DAGs. The gateway handles all of that.\n *\n * @example\n * ```ts\n * const session = await client.start({ studio_address: '0x...', agent_address: '0x...' });\n * await session.log({ summary: 'Planning cache layer implementation' });\n * await session.step('implementing', 'Added CacheService class');\n * await session.step('testing', 'All 47 tests pass');\n * const { workflow_id, data_hash } = await session.complete();\n * ```\n */\n\nimport { randomUUID } from 'node:crypto';\nimport axios, { AxiosError } from 'axios';\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/** Valid agent roles accepted by the gateway for session events. */\nexport type SessionAgentRole = 'worker' | 'verifier' | 'collaborator';\n\n/** Per-event agent override. */\nexport interface SessionAgentOverride {\n  /** Wallet address of the agent emitting this event. */\n  agent_address: string;\n  /** Agent role (defaults to `\"worker\"`). Must be `worker`, `verifier`, or `collaborator`. */\n  role?: SessionAgentRole;\n}\n\n/** Options for {@link Session.log}. */\nexport interface SessionLogOptions {\n  /** Human-readable description of what happened. */\n  summary: string;\n  /** Canonical event type. Defaults to `\"artifact_created\"`. */\n  event_type?: string;\n  /** Arbitrary metadata attached to the event. */\n  metadata?: Record<string, unknown>;\n  /** Override the session-level agent for this event. */\n  agent?: SessionAgentOverride;\n}\n\n/** Result returned by {@link Session.complete}. */\nexport interface SessionCompleteResult {\n  workflow_id: string | null;\n  data_hash: string | null;\n}\n\n/** Canonical event-type mappings for {@link Session.step}. */\nconst STEP_TYPE_MAP: Record<string, string> = {\n  planning: 'plan_created',\n  testing: 'test_run',\n  debugging: 'debug_step',\n  implementing: 'file_written',\n  completing: 'submission_created',\n};\n\n// =============================================================================\n// Session\n// =============================================================================\n\nexport class Session {\n  /** Session ID returned by the gateway. */\n  public readonly sessionId: string;\n\n  private readonly gatewayUrl: string;\n  private readonly apiKey: string | undefined;\n  private readonly studioAddress: string;\n  private readonly agentAddress: string;\n  private readonly studioPolicyVersion: string;\n  private readonly workMandateId: string;\n  private readonly taskType: string;\n  private lastEventId: string | null;\n\n  /** @internal — use {@link SessionClient.start} to create instances. */\n  constructor(opts: {\n    sessionId: string;\n    gatewayUrl: string;\n    apiKey?: string;\n    lastEventId?: string | null;\n    studioAddress: string;\n    agentAddress: string;\n    studioPolicyVersion: string;\n    workMandateId: string;\n    taskType: string;\n  }) {\n    this.sessionId = opts.sessionId;\n    this.gatewayUrl = opts.gatewayUrl;\n    this.apiKey = opts.apiKey;\n    this.lastEventId = opts.lastEventId ?? null;\n    this.studioAddress = opts.studioAddress;\n    this.agentAddress = opts.agentAddress;\n    this.studioPolicyVersion = opts.studioPolicyVersion;\n    this.workMandateId = opts.workMandateId;\n    this.taskType = opts.taskType;\n  }\n\n  /**\n   * Log a session event.\n   *\n   * Automatically generates `event_id`, `timestamp`, and chains `parent_event_ids`\n   * from the previous event so the gateway can build a causal DAG.\n   *\n   * @param opts - Event details. Only `summary` is required.\n   * @throws Error if the gateway returns a non-2xx status.\n   */\n  async log(opts: SessionLogOptions): Promise<void> {\n    const eventId = randomUUID();\n    const event = {\n      event_id: eventId,\n      event_type: opts.event_type ?? 'artifact_created',\n      timestamp: new Date().toISOString(),\n      summary: opts.summary,\n      causality: {\n        parent_event_ids: this.lastEventId ? [this.lastEventId] : [],\n      },\n      agent: {\n        agent_address: opts.agent?.agent_address ?? this.agentAddress,\n        role: opts.agent?.role ?? 'worker',\n      },\n      studio: {\n        studio_address: this.studioAddress,\n        studio_policy_version: this.studioPolicyVersion,\n      },\n      task: {\n        work_mandate_id: this.workMandateId,\n        task_type: this.taskType,\n      },\n      ...(opts.metadata ? { metadata: opts.metadata } : {}),\n    };\n\n    await this.post(`/v1/sessions/${this.sessionId}/events`, [event]);\n    this.lastEventId = eventId;\n  }\n\n  /**\n   * Convenience wrapper around {@link log} that maps human-friendly step names\n   * to canonical event types.\n   *\n   * Mappings:\n   * - `\"planning\"` → `plan_created`\n   * - `\"testing\"` → `test_run`\n   * - `\"debugging\"` → `debug_step`\n   * - `\"implementing\"` → `file_written`\n   * - `\"completing\"` → `submission_created`\n   *\n   * Unknown step types fall back to `artifact_created`.\n   *\n   * @param stepType - Friendly step name.\n   * @param summary - What happened in this step.\n   */\n  async step(stepType: string, summary: string, agent?: SessionAgentOverride): Promise<void> {\n    const eventType = STEP_TYPE_MAP[stepType] ?? 'artifact_created';\n    await this.log({ event_type: eventType, summary, agent });\n  }\n\n  /**\n   * Complete the session.\n   *\n   * Triggers the on-chain WorkSubmission workflow (if the gateway is configured for it)\n   * and returns `workflow_id` + `data_hash` for downstream verification/scoring.\n   *\n   * @param opts - Optional status (`\"completed\"` | `\"failed\"`) and summary.\n   * @returns `{ workflow_id, data_hash }` — both may be `null` if the gateway\n   *          workflow engine is not configured.\n   * @throws Error if the gateway returns a non-2xx status.\n   */\n  async complete(\n    opts?: { status?: 'completed' | 'failed'; summary?: string },\n  ): Promise<SessionCompleteResult> {\n    const body: Record<string, unknown> = {};\n    if (opts?.status) body.status = opts.status;\n    if (opts?.summary) body.summary = opts.summary;\n\n    const data = await this.post<{\n      data: { workflow_id: string | null; data_hash: string | null };\n    }>(`/v1/sessions/${this.sessionId}/complete`, body);\n\n    return {\n      workflow_id: data.data?.workflow_id ?? null,\n      data_hash: data.data?.data_hash ?? null,\n    };\n  }\n\n  // ---------------------------------------------------------------------------\n  // Internal HTTP helper\n  // ---------------------------------------------------------------------------\n\n  private async post<T = unknown>(path: string, body: unknown): Promise<T> {\n    const url = `${this.gatewayUrl}${path}`;\n    const headers: Record<string, string> = { 'Content-Type': 'application/json' };\n    if (this.apiKey) headers['X-API-Key'] = this.apiKey;\n\n    try {\n      const res = await axios({ method: 'POST', url, data: body, headers, timeout: 30_000 });\n      return res.data as T;\n    } catch (err) {\n      const axiosErr = err as AxiosError;\n      const status = axiosErr.response?.status ?? 0;\n      const detail = JSON.stringify(axiosErr.response?.data ?? axiosErr.message);\n      throw new Error(`Session request failed: POST ${path} → ${status} ${detail}`);\n    }\n  }\n}\n","/**\n * SessionClient — factory for creating ChaosChain Engineering Studio sessions.\n *\n * @example\n * ```ts\n * import { SessionClient } from '@chaoschain/sdk';\n *\n * const client = new SessionClient({ gatewayUrl: 'https://gateway.chaoscha.in', apiKey: 'cc_...' });\n * const session = await client.start({\n *   studio_address: '0xFA0795fD5D7F58eCAa7Eae35Ad9cB8AED9424Dd0',\n *   agent_address: '0x9B4Cef62a0ce1671ccFEFA6a6D8cBFa165c49831',\n *   task_type: 'feature',\n * });\n *\n * await session.log({ summary: 'Started implementing cache layer' });\n * await session.step('testing', 'All tests pass');\n * const result = await session.complete();\n * ```\n */\n\nimport axios, { AxiosError } from 'axios';\nimport { Session } from './Session';\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/** Configuration for {@link SessionClient}. */\nexport interface SessionClientConfig {\n  /** Gateway base URL (default: `\"https://gateway.chaoscha.in\"`). */\n  gatewayUrl?: string;\n  /** API key sent as `X-API-Key` header. */\n  apiKey?: string;\n}\n\n/** Options for {@link SessionClient.start}. */\nexport interface SessionStartOptions {\n  /** Studio contract address (required). */\n  studio_address: string;\n  /** Worker agent wallet address (required). */\n  agent_address: string;\n  /** Work mandate ID (default: `\"generic-task\"`). */\n  work_mandate_id?: string;\n  /** Task classification (default: `\"general\"`). */\n  task_type?: string;\n  /** Studio policy version (default: `\"engineering-studio-default-v1\"`). */\n  studio_policy_version?: string;\n  /** Client-provided session ID. Server generates one if omitted. */\n  session_id?: string;\n}\n\n// =============================================================================\n// SessionClient\n// =============================================================================\n\nexport class SessionClient {\n  private readonly gatewayUrl: string;\n  private readonly apiKey: string | undefined;\n\n  constructor(config: SessionClientConfig = {}) {\n    this.gatewayUrl = (config.gatewayUrl ?? 'https://gateway.chaoscha.in').replace(/\\/$/, '');\n    this.apiKey = config.apiKey;\n  }\n\n  /**\n   * Create a new coding session on the gateway.\n   *\n   * Returns a {@link Session} instance that can be used to log events, run steps,\n   * and complete the session. The gateway persists all events and constructs the\n   * Evidence DAG automatically.\n   *\n   * @param opts - Session creation parameters.\n   * @returns A live {@link Session} bound to the newly created session ID.\n   * @throws Error if the gateway returns a non-2xx status.\n   */\n  async start(opts: SessionStartOptions): Promise<Session> {\n    const body: Record<string, string> = {\n      studio_address: opts.studio_address,\n      agent_address: opts.agent_address,\n    };\n    if (opts.work_mandate_id) body.work_mandate_id = opts.work_mandate_id;\n    if (opts.task_type) body.task_type = opts.task_type;\n    if (opts.studio_policy_version) body.studio_policy_version = opts.studio_policy_version;\n    if (opts.session_id) body.session_id = opts.session_id;\n\n    const url = `${this.gatewayUrl}/v1/sessions`;\n    const headers: Record<string, string> = { 'Content-Type': 'application/json' };\n    if (this.apiKey) headers['X-API-Key'] = this.apiKey;\n\n    let data: { data: { session_id: string } };\n    try {\n      const res = await axios({ method: 'POST', url, data: body, headers, timeout: 30_000 });\n      data = res.data as typeof data;\n    } catch (err) {\n      const axiosErr = err as AxiosError;\n      const status = axiosErr.response?.status ?? 0;\n      const detail = JSON.stringify(axiosErr.response?.data ?? axiosErr.message);\n      throw new Error(`Failed to create session: POST /v1/sessions → ${status} ${detail}`);\n    }\n\n    const sessionId = data.data?.session_id;\n    if (!sessionId) {\n      throw new Error('Gateway response missing session_id');\n    }\n\n    return new Session({\n      sessionId,\n      gatewayUrl: this.gatewayUrl,\n      apiKey: this.apiKey,\n      studioAddress: opts.studio_address,\n      agentAddress: opts.agent_address,\n      studioPolicyVersion: opts.studio_policy_version ?? 'engineering-studio-default-v1',\n      workMandateId: opts.work_mandate_id ?? 'generic-task',\n      taskType: opts.task_type ?? 'general',\n    });\n  }\n}\n"]}
+{"version":3,"sources":["../../src/session/Session.ts","../../src/session/SessionClient.ts"],"names":["axios"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Session — high-level wrapper for ChaosChain Engineering Studio sessions.\n *\n * Agents use this class to log work events without constructing raw event schemas,\n * managing parent IDs, or thinking about DAGs. The gateway handles all of that.\n *\n * @example\n * ```ts\n * const session = await client.start({ studio_address: '0x...', agent_address: '0x...' });\n * await session.log({ summary: 'Planning cache layer implementation' });\n * await session.step('implementing', 'Added CacheService class');\n * await session.step('testing', 'All 47 tests pass');\n * const { workflow_id, data_hash } = await session.complete();\n * ```\n */\n\nimport { randomUUID } from 'node:crypto';\nimport axios, { AxiosError } from 'axios';\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/** Valid agent roles accepted by the gateway for session events. */\nexport type SessionAgentRole = 'worker' | 'verifier' | 'collaborator';\n\n/** Per-event agent override. */\nexport interface SessionAgentOverride {\n  /** Wallet address of the agent emitting this event. */\n  agent_address: string;\n  /** Agent role (defaults to `\"worker\"`). Must be `worker`, `verifier`, or `collaborator`. */\n  role?: SessionAgentRole;\n}\n\n/** Options for {@link Session.log}. */\nexport interface SessionLogOptions {\n  /** Human-readable description of what happened. */\n  summary: string;\n  /** Canonical event type. Defaults to `\"artifact_created\"`. */\n  event_type?: string;\n  /** Arbitrary metadata attached to the event. */\n  metadata?: Record<string, unknown>;\n  /** Override the session-level agent for this event. */\n  agent?: SessionAgentOverride;\n}\n\n/** Result returned by {@link Session.complete}. */\nexport interface SessionCompleteResult {\n  workflow_id: string | null;\n  data_hash: string | null;\n  epoch: number;\n}\n\n/** Canonical event-type mappings for {@link Session.step}. */\nconst STEP_TYPE_MAP: Record<string, string> = {\n  planning: 'plan_created',\n  testing: 'test_run',\n  debugging: 'debug_step',\n  implementing: 'file_written',\n  completing: 'submission_created',\n};\n\n// =============================================================================\n// Session\n// =============================================================================\n\nexport class Session {\n  /** Session ID returned by the gateway. */\n  public readonly sessionId: string;\n  /** Epoch number returned by the gateway. */\n  public readonly epoch: number;\n  /** Studio contract address for this session. */\n  public readonly studioAddress: string;\n  /** Default agent wallet address for this session. */\n  public readonly agentAddress: string;\n  /** URL to view this session's Evidence DAG in the browser. */\n  public readonly viewerUrl: string;\n\n  private readonly gatewayUrl: string;\n  private readonly apiKey: string | undefined;\n  private readonly studioPolicyVersion: string;\n  private readonly workMandateId: string;\n  private readonly taskType: string;\n  private lastEventId: string | null;\n\n  /** @internal — use {@link SessionClient.start} to create instances. */\n  constructor(opts: {\n    sessionId: string;\n    gatewayUrl: string;\n    apiKey?: string;\n    lastEventId?: string | null;\n    studioAddress: string;\n    agentAddress: string;\n    studioPolicyVersion: string;\n    workMandateId: string;\n    taskType: string;\n    epoch: number;\n  }) {\n    this.sessionId = opts.sessionId;\n    this.epoch = opts.epoch;\n    this.viewerUrl = `${opts.gatewayUrl}/v1/sessions/${opts.sessionId}/viewer`;\n    this.gatewayUrl = opts.gatewayUrl;\n    this.apiKey = opts.apiKey;\n    this.lastEventId = opts.lastEventId ?? null;\n    this.studioAddress = opts.studioAddress;\n    this.agentAddress = opts.agentAddress;\n    this.studioPolicyVersion = opts.studioPolicyVersion;\n    this.workMandateId = opts.workMandateId;\n    this.taskType = opts.taskType;\n  }\n\n  /**\n   * Log a session event.\n   *\n   * Automatically generates `event_id`, `timestamp`, and chains `parent_event_ids`\n   * from the previous event so the gateway can build a causal DAG.\n   *\n   * @param opts.summary - Human-readable description of what happened (required).\n   * @param opts.event_type - Canonical event type (default: `\"artifact_created\"`).\n   * @param opts.metadata - Arbitrary key-value metadata attached to the event.\n   * @param opts.agent - Override the session-level agent for this event.\n   *   Pass `{ agent_address, role? }` to emit the event from a different agent.\n   *   Valid roles: `\"worker\"`, `\"verifier\"`, `\"collaborator\"`. Defaults to `\"worker\"`.\n   * @throws Error if the gateway returns a non-2xx status.\n   */\n  async log(opts: SessionLogOptions): Promise<void> {\n    const eventId = randomUUID();\n    const event = {\n      event_id: eventId,\n      event_type: opts.event_type ?? 'artifact_created',\n      timestamp: new Date().toISOString(),\n      summary: opts.summary,\n      causality: {\n        parent_event_ids: this.lastEventId ? [this.lastEventId] : [],\n      },\n      agent: {\n        agent_address: opts.agent?.agent_address ?? this.agentAddress,\n        role: opts.agent?.role ?? 'worker',\n      },\n      studio: {\n        studio_address: this.studioAddress,\n        studio_policy_version: this.studioPolicyVersion,\n      },\n      task: {\n        work_mandate_id: this.workMandateId,\n        task_type: this.taskType,\n      },\n      ...(opts.metadata ? { metadata: opts.metadata } : {}),\n    };\n\n    await this.post(`/v1/sessions/${this.sessionId}/events`, [event]);\n    this.lastEventId = eventId;\n  }\n\n  /**\n   * Convenience wrapper around {@link log} that maps human-friendly step names\n   * to canonical event types.\n   *\n   * Mappings:\n   * - `\"planning\"` → `plan_created`\n   * - `\"testing\"` → `test_run`\n   * - `\"debugging\"` → `debug_step`\n   * - `\"implementing\"` → `file_written`\n   * - `\"completing\"` → `submission_created`\n   *\n   * Unknown step types fall back to `artifact_created`.\n   *\n   * @param stepType - Friendly step name (`\"planning\"`, `\"implementing\"`, `\"testing\"`, `\"debugging\"`, `\"completing\"`).\n   * @param summary - What happened in this step.\n   * @param agent - Optional agent override for this event. Same as `log({ agent })`.\n   */\n  async step(stepType: string, summary: string, agent?: SessionAgentOverride): Promise<void> {\n    const eventType = STEP_TYPE_MAP[stepType] ?? 'artifact_created';\n    await this.log({ event_type: eventType, summary, agent });\n  }\n\n  /**\n   * Complete the session.\n   *\n   * Triggers the on-chain WorkSubmission workflow (if the gateway is configured for it)\n   * and returns the session result.\n   *\n   * @param opts.status - `\"completed\"` or `\"failed\"` (default: `\"completed\"`).\n   * @param opts.summary - Human-readable summary of the session outcome.\n   * @returns `{ workflow_id, data_hash, epoch }` — `workflow_id` and `data_hash`\n   *          may be `null` if the gateway workflow engine is not configured.\n   *          `epoch` is the epoch this session belongs to.\n   * @throws Error if the gateway returns a non-2xx status.\n   */\n  async complete(\n    opts?: { status?: 'completed' | 'failed'; summary?: string },\n  ): Promise<SessionCompleteResult> {\n    const body: Record<string, unknown> = {};\n    if (opts?.status) body.status = opts.status;\n    if (opts?.summary) body.summary = opts.summary;\n\n    const data = await this.post<{\n      data: { workflow_id: string | null; data_hash: string | null; epoch: number };\n    }>(`/v1/sessions/${this.sessionId}/complete`, body);\n\n    return {\n      workflow_id: data.data?.workflow_id ?? null,\n      data_hash: data.data?.data_hash ?? null,\n      epoch: data.data.epoch,\n    };\n  }\n\n  // ---------------------------------------------------------------------------\n  // Internal HTTP helper\n  // ---------------------------------------------------------------------------\n\n  private async post<T = unknown>(path: string, body: unknown): Promise<T> {\n    const url = `${this.gatewayUrl}${path}`;\n    const headers: Record<string, string> = { 'Content-Type': 'application/json' };\n    if (this.apiKey) headers['X-API-Key'] = this.apiKey;\n\n    try {\n      const res = await axios({ method: 'POST', url, data: body, headers, timeout: 30_000 });\n      return res.data as T;\n    } catch (err) {\n      const axiosErr = err as AxiosError;\n      const status = axiosErr.response?.status ?? 0;\n      const detail = JSON.stringify(axiosErr.response?.data ?? axiosErr.message);\n      throw new Error(`Session request failed: POST ${path} → ${status} ${detail}`);\n    }\n  }\n}\n","/**\n * SessionClient — factory for creating ChaosChain Engineering Studio sessions.\n *\n * @example\n * ```ts\n * import { SessionClient } from '@chaoschain/sdk';\n *\n * const client = new SessionClient({ gatewayUrl: 'https://gateway.chaoscha.in', apiKey: 'cc_...' });\n * const session = await client.start({\n *   studio_address: '0xFA0795fD5D7F58eCAa7Eae35Ad9cB8AED9424Dd0',\n *   agent_address: '0x9B4Cef62a0ce1671ccFEFA6a6D8cBFa165c49831',\n *   task_type: 'feature',\n * });\n *\n * await session.log({ summary: 'Started implementing cache layer' });\n * await session.step('testing', 'All tests pass');\n * const result = await session.complete();\n * ```\n */\n\nimport axios, { AxiosError } from 'axios';\nimport { Session } from './Session';\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/** Configuration for {@link SessionClient}. */\nexport interface SessionClientConfig {\n  /** Gateway base URL (default: `\"https://gateway.chaoscha.in\"`). */\n  gatewayUrl?: string;\n  /** API key sent as `X-API-Key` header. */\n  apiKey?: string;\n}\n\n/** Options for {@link SessionClient.start}. */\nexport interface SessionStartOptions {\n  /** Studio contract address (required). */\n  studio_address: string;\n  /** Worker agent wallet address (required). */\n  agent_address: string;\n  /** Work mandate ID (default: `\"generic-task\"`). */\n  work_mandate_id?: string;\n  /** Task classification (default: `\"general\"`). */\n  task_type?: string;\n  /** Studio policy version (default: `\"engineering-studio-default-v1\"`). */\n  studio_policy_version?: string;\n  /** Client-provided session ID. Server generates one if omitted. */\n  session_id?: string;\n}\n\n// =============================================================================\n// SessionClient\n// =============================================================================\n\nexport class SessionClient {\n  private readonly gatewayUrl: string;\n  private readonly apiKey: string | undefined;\n\n  constructor(config: SessionClientConfig = {}) {\n    this.gatewayUrl = (config.gatewayUrl ?? 'https://gateway.chaoscha.in').replace(/\\/$/, '');\n    this.apiKey = config.apiKey;\n  }\n\n  /**\n   * Create a new coding session on the gateway.\n   *\n   * Returns a {@link Session} instance that can be used to log events, run steps,\n   * and complete the session. The gateway persists all events and constructs the\n   * Evidence DAG automatically.\n   *\n   * The returned session exposes `session.sessionId`, `session.epoch`,\n   * `session.studioAddress`, and `session.agentAddress`.\n   *\n   * @param opts.studio_address - Studio contract address (required).\n   * @param opts.agent_address - Worker agent wallet address (required).\n   * @param opts.task_type - Task classification: `\"feature\"`, `\"bugfix\"`, `\"refactor\"`, etc. (default: `\"general\"`).\n   * @param opts.work_mandate_id - Work mandate identifier (default: `\"generic-task\"`).\n   * @param opts.studio_policy_version - Studio policy version (default: `\"engineering-studio-default-v1\"`).\n   * @param opts.session_id - Client-provided session ID. Server generates one if omitted.\n   * @returns A live {@link Session} bound to the newly created session ID and epoch.\n   * @throws Error if the gateway returns a non-2xx status.\n   */\n  async start(opts: SessionStartOptions): Promise<Session> {\n    const body: Record<string, string> = {\n      studio_address: opts.studio_address,\n      agent_address: opts.agent_address,\n    };\n    if (opts.work_mandate_id) body.work_mandate_id = opts.work_mandate_id;\n    if (opts.task_type) body.task_type = opts.task_type;\n    if (opts.studio_policy_version) body.studio_policy_version = opts.studio_policy_version;\n    if (opts.session_id) body.session_id = opts.session_id;\n\n    const url = `${this.gatewayUrl}/v1/sessions`;\n    const headers: Record<string, string> = { 'Content-Type': 'application/json' };\n    if (this.apiKey) headers['X-API-Key'] = this.apiKey;\n\n    let data: { data: { session_id: string; epoch: number } };\n    try {\n      const res = await axios({ method: 'POST', url, data: body, headers, timeout: 30_000 });\n      data = res.data as typeof data;\n    } catch (err) {\n      const axiosErr = err as AxiosError;\n      const status = axiosErr.response?.status ?? 0;\n      const detail = JSON.stringify(axiosErr.response?.data ?? axiosErr.message);\n      throw new Error(`Failed to create session: POST /v1/sessions → ${status} ${detail}`);\n    }\n\n    const sessionId = data.data?.session_id;\n    if (!sessionId) {\n      throw new Error('Gateway response missing session_id');\n    }\n\n    return new Session({\n      sessionId,\n      gatewayUrl: this.gatewayUrl,\n      apiKey: this.apiKey,\n      studioAddress: opts.studio_address,\n      agentAddress: opts.agent_address,\n      studioPolicyVersion: opts.studio_policy_version ?? 'engineering-studio-default-v1',\n      workMandateId: opts.work_mandate_id ?? 'generic-task',\n      taskType: opts.task_type ?? 'general',\n      epoch: data.data.epoch,\n    });\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaoschain/sdk",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "type": "module",
   "description": "TypeScript SDK for building verifiable AI agents on ChaosChain",
   "main": "./dist/index.cjs",