@chaoschain/sdk 0.3.1 → 0.3.3

package/dist/providers/compute/index.d.cts

@@ -1,4 +1,4 @@
-import { o as ComputeProvider } from '../../types-BBVtx_jV.cjs';
+import { C as ComputeProvider } from '../../types-C0Ay90UI.cjs';
 import 'ethers';
 
 /**

package/dist/providers/compute/index.d.ts

@@ -1,4 +1,4 @@
-import { o as ComputeProvider } from '../../types-BBVtx_jV.js';
+import { C as ComputeProvider } from '../../types-C0Ay90UI.js';
 import 'ethers';
 
 /**

package/dist/providers/storage/index.d.cts

@@ -1,5 +1,5 @@
-export { I as IPFSLocalStorage } from '../../IPFSLocal-zRj6kG8e.cjs';
-import { n as StorageProvider, U as UploadOptions, i as UploadResult } from '../../types-BBVtx_jV.cjs';
+export { I as IPFSLocalStorage } from '../../IPFSLocal-DjFddwHD.cjs';
+import { S as StorageProvider, U as UploadOptions, a as UploadResult } from '../../types-C0Ay90UI.cjs';
 import 'ethers';
 
 /**

package/dist/providers/storage/index.d.ts

@@ -1,5 +1,5 @@
-export { I as IPFSLocalStorage } from '../../IPFSLocal-B4hnMEfS.js';
-import { n as StorageProvider, U as UploadOptions, i as UploadResult } from '../../types-BBVtx_jV.js';
+export { I as IPFSLocalStorage } from '../../IPFSLocal-B_Sgmd_Q.js';
+import { S as StorageProvider, U as UploadOptions, a as UploadResult } from '../../types-C0Ay90UI.js';
 import 'ethers';
 
 /**

package/dist/session/index.cjs

@@ -0,0 +1,222 @@
+'use strict';
+
+var crypto = require('crypto');
+var axios = require('axios');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var axios__default = /*#__PURE__*/_interopDefault(axios);
+
+// src/session/Session.ts
+var STEP_TYPE_MAP = {
+  planning: "plan_created",
+  testing: "test_run",
+  debugging: "debug_step",
+  implementing: "file_written",
+  completing: "submission_created"
+};
+var Session = class {
+  /** Session ID returned by the gateway. */
+  sessionId;
+  /** 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;
+  lastEventId;
+  /** @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;
+    this.studioAddress = opts.studioAddress;
+    this.agentAddress = opts.agentAddress;
+    this.studioPolicyVersion = opts.studioPolicyVersion;
+    this.workMandateId = opts.workMandateId;
+    this.taskType = opts.taskType;
+  }
+  /**
+   * Log a session event.
+   *
+   * Automatically generates `event_id`, `timestamp`, and chains `parent_event_ids`
+   * from the previous event so the gateway can build a causal DAG.
+   *
+   * @param opts.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) {
+    const eventId = crypto.randomUUID();
+    const event = {
+      event_id: eventId,
+      event_type: opts.event_type ?? "artifact_created",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      summary: opts.summary,
+      causality: {
+        parent_event_ids: this.lastEventId ? [this.lastEventId] : []
+      },
+      agent: {
+        agent_address: opts.agent?.agent_address ?? this.agentAddress,
+        role: opts.agent?.role ?? "worker"
+      },
+      studio: {
+        studio_address: this.studioAddress,
+        studio_policy_version: this.studioPolicyVersion
+      },
+      task: {
+        work_mandate_id: this.workMandateId,
+        task_type: this.taskType
+      },
+      ...opts.metadata ? { metadata: opts.metadata } : {}
+    };
+    await this.post(`/v1/sessions/${this.sessionId}/events`, [event]);
+    this.lastEventId = eventId;
+  }
+  /**
+   * Convenience wrapper around {@link log} that maps human-friendly step names
+   * to canonical event types.
+   *
+   * Mappings:
+   * - `"planning"` → `plan_created`
+   * - `"testing"` → `test_run`
+   * - `"debugging"` → `debug_step`
+   * - `"implementing"` → `file_written`
+   * - `"completing"` → `submission_created`
+   *
+   * Unknown step types fall back to `artifact_created`.
+   *
+   * @param stepType - Friendly step name (`"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";
+    await this.log({ event_type: eventType, summary, agent });
+  }
+  /**
+   * Complete the session.
+   *
+   * Triggers the on-chain WorkSubmission workflow (if the gateway is configured for it)
+   * and returns the session result.
+   *
+   * @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) {
+    const body = {};
+    if (opts?.status) body.status = opts.status;
+    if (opts?.summary) body.summary = opts.summary;
+    const data = await this.post(`/v1/sessions/${this.sessionId}/complete`, body);
+    return {
+      workflow_id: data.data?.workflow_id ?? null,
+      data_hash: data.data?.data_hash ?? null,
+      epoch: data.data.epoch
+    };
+  }
+  // ---------------------------------------------------------------------------
+  // Internal HTTP helper
+  // ---------------------------------------------------------------------------
+  async post(path, body) {
+    const url = `${this.gatewayUrl}${path}`;
+    const headers = { "Content-Type": "application/json" };
+    if (this.apiKey) headers["X-API-Key"] = this.apiKey;
+    try {
+      const res = await axios__default.default({ method: "POST", url, data: body, headers, timeout: 3e4 });
+      return res.data;
+    } catch (err) {
+      const axiosErr = err;
+      const status = axiosErr.response?.status ?? 0;
+      const detail = JSON.stringify(axiosErr.response?.data ?? axiosErr.message);
+      throw new Error(`Session request failed: POST ${path} \u2192 ${status} ${detail}`);
+    }
+  }
+};
+var SessionClient = class {
+  gatewayUrl;
+  apiKey;
+  constructor(config = {}) {
+    this.gatewayUrl = (config.gatewayUrl ?? "https://gateway.chaoscha.in").replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+  }
+  /**
+   * Create a new coding session on the gateway.
+   *
+   * Returns a {@link Session} instance that can be used to log events, run steps,
+   * and complete the session. The gateway persists all events and constructs the
+   * Evidence DAG automatically.
+   *
+   * 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) {
+    const body = {
+      studio_address: opts.studio_address,
+      agent_address: opts.agent_address
+    };
+    if (opts.work_mandate_id) body.work_mandate_id = opts.work_mandate_id;
+    if (opts.task_type) body.task_type = opts.task_type;
+    if (opts.studio_policy_version) body.studio_policy_version = opts.studio_policy_version;
+    if (opts.session_id) body.session_id = opts.session_id;
+    const url = `${this.gatewayUrl}/v1/sessions`;
+    const headers = { "Content-Type": "application/json" };
+    if (this.apiKey) headers["X-API-Key"] = this.apiKey;
+    let data;
+    try {
+      const res = await axios__default.default({ method: "POST", url, data: body, headers, timeout: 3e4 });
+      data = res.data;
+    } catch (err) {
+      const axiosErr = err;
+      const status = axiosErr.response?.status ?? 0;
+      const detail = JSON.stringify(axiosErr.response?.data ?? axiosErr.message);
+      throw new Error(`Failed to create session: POST /v1/sessions \u2192 ${status} ${detail}`);
+    }
+    const sessionId = data.data?.session_id;
+    if (!sessionId) {
+      throw new Error("Gateway response missing session_id");
+    }
+    return new Session({
+      sessionId,
+      gatewayUrl: this.gatewayUrl,
+      apiKey: this.apiKey,
+      studioAddress: opts.studio_address,
+      agentAddress: opts.agent_address,
+      studioPolicyVersion: opts.studio_policy_version ?? "engineering-studio-default-v1",
+      workMandateId: opts.work_mandate_id ?? "generic-task",
+      taskType: opts.task_type ?? "general",
+      epoch: data.data.epoch
+    });
+  }
+};
+
+exports.Session = Session;
+exports.SessionClient = SessionClient;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/session/index.cjs.map

@@ -0,0 +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  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

@@ -0,0 +1,193 @@
+/**
+ * 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;
+    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 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;
+        epoch: number;
+    });
+    /**
+     * 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.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>;
+    /**
+     * 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 (`"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 the session result.
+     *
+     * @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?: {
+        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.
+     *
+     * 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>;
+}
+
+export { Session, type SessionAgentOverride, type SessionAgentRole, SessionClient, type SessionClientConfig, type SessionCompleteResult, type SessionLogOptions, type SessionStartOptions };