neosigma-sdk 0.1.0 → 0.2.0

package/README.md

@@ -1,7 +1,7 @@
 # neosigma-sdk
 
 NeoSigma TypeScript SDK. Emit product events that join your agent traces on
-`run_id`, in NeoSigma's own telemetry store.
+`turn_id`, in NeoSigma's own telemetry store.
 
 ## Quick start
 
@@ -11,7 +11,7 @@ import { init, trace, capture, identify, installShutdownHandlers } from "neosigm
 init(); // reads NEOSIGMA_API_KEY / NEOSIGMA_EVENTS_ENDPOINT; dark without a key
 installShutdownHandlers(); // flush queued events on SIGTERM/SIGINT
 
-await trace({ runId: run.id, distinctId: userId }, async () => {
+await trace({ turnId: turn.id, distinctId: userId }, async () => {
   identify(userId, { plan: "pro" });
   capture("message sent", { length: text.length });
 });
@@ -19,9 +19,9 @@ await trace({ runId: run.id, distinctId: userId }, async () => {
 
 ## How it joins
 
-`run_id` is the durable join key back to the agent's spans. Bind it once with
-`trace({ runId })`; every `capture()` inside that scope carries it, so product
-events sit next to the model's spans for the same run in ClickHouse. The ingest
+`turn_id` is the durable join key back to the agent's spans. Bind it once with
+`trace({ turnId })`; every `capture()` inside that scope carries it, so product
+events sit next to the model's spans for the same turn in ClickHouse. The ingest
 resolves your API key to an `org_id` server-side (the client never sends it).
 
 ## Configuration
@@ -49,5 +49,5 @@ the environment.
 ## Correlation across processes
 
 `AsyncLocalStorage` does not cross a queue or process hop. When you hand work to
-another service or a background job, pass `run.id` in the payload and re-bind it
-on the far side with `trace({ runId })` (the Python SDK follows the same rule).
+another service or a background job, pass the turn id in the payload and re-bind it
+on the far side with `trace({ turnId })` (the Python SDK follows the same rule).

package/dist/context.d.ts

@@ -1,17 +1,17 @@
-/** The ambient run-correlation ids: the join spine for events + spans. */
+/** The ambient turn-correlation ids: the join spine for events + spans. */
 export interface Correlation {
-    runId: string;
+    turnId: string;
     distinctId: string;
     sessionId: string;
 }
-export declare function currentRunId(): string;
+export declare function currentTurnId(): string;
 export declare function currentDistinctId(): string;
 export declare function currentSessionId(): string;
 /**
  * Run `fn` with the given correlation ids bound (only non-empty ones overlay the
  * parent scope), returning `fn`'s value. AsyncLocalStorage propagates the store
  * across awaits within this async context, but NOT across a process/queue hop:
- * thread runId into the job payload and re-bind it on the far side, exactly as
+ * thread turnId into the job payload and re-bind it on the far side, exactly as
  * the Python SDK requires.
  *
  * Each distinct actor should own its own `trace()` frame. `setDistinctId` mutates
@@ -20,7 +20,7 @@ export declare function currentSessionId(): string;
  * wins); give each its own `trace({ distinctId })` frame instead.
  */
 export declare function trace<T>(opts: {
-    runId?: string;
+    turnId?: string;
     distinctId?: string;
     sessionId?: string;
 }, fn: () => T): T;

package/dist/context.js

@@ -8,8 +8,8 @@ let outsideScopeDrops = 0;
 function store() {
     return als.getStore();
 }
-export function currentRunId() {
-    return store()?.runId ?? "";
+export function currentTurnId() {
+    return store()?.turnId ?? "";
 }
 export function currentDistinctId() {
     return store()?.distinctId ?? "";
@@ -21,7 +21,7 @@ export function currentSessionId() {
  * Run `fn` with the given correlation ids bound (only non-empty ones overlay the
  * parent scope), returning `fn`'s value. AsyncLocalStorage propagates the store
  * across awaits within this async context, but NOT across a process/queue hop:
- * thread runId into the job payload and re-bind it on the far side, exactly as
+ * thread turnId into the job payload and re-bind it on the far side, exactly as
  * the Python SDK requires.
  *
  * Each distinct actor should own its own `trace()` frame. `setDistinctId` mutates
@@ -32,7 +32,7 @@ export function currentSessionId() {
 export function trace(opts, fn) {
     const parent = store();
     const merged = {
-        runId: opts.runId || parent?.runId || "",
+        turnId: opts.turnId || parent?.turnId || "",
         distinctId: opts.distinctId || parent?.distinctId || "",
         sessionId: opts.sessionId || parent?.sessionId || "",
     };
@@ -58,6 +58,6 @@ export function setDistinctId(distinctId) {
     if (crossedWarnBoundary(prev, 1)) {
         console.warn(`[neosigma] setDistinctId/identify called outside a trace() scope ` +
             `(${outsideScopeDrops} dropped); ignored. Wrap request handling in ` +
-            `trace({ runId }, ...) so identity stays per-request.`);
+            `trace({ turnId }, ...) so identity stays per-request.`);
     }
 }

package/dist/events.d.ts

@@ -21,8 +21,8 @@ export interface ProductEvent {
     event_name: string;
     /** Analytics actor; "" when anonymous. */
     distinct_id: string;
-    /** Durable join key back to agent spans; "" outside a correlated run. */
-    run_id: string;
+    /** Durable join key back to the turn's spans; "" outside a turn scope. */
+    turn_id: string;
     /** Optional framework/session id. */
     session_id: string;
     /** Best-effort OTel trace id; "" when no active span. */

package/dist/events.js

@@ -20,7 +20,7 @@ export const WIRE_FIELDS = [
     "event_uuid",
     "event_name",
     "distinct_id",
-    "run_id",
+    "turn_id",
     "session_id",
     "trace_id",
     "timestamp_ns",

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export declare function init(overrides?: {
     enabled?: boolean;
 }): void;
 /**
- * Emit a product event, stamped with the ambient run-correlation ids (bound by
+ * Emit a product event, stamped with the ambient turn-correlation ids (bound by
  * trace()). Mints an idempotency event_uuid and a call-site timestamp, and
  * sanitizes properties to wire-safe scalars. Fail-open: never throws.
  */

package/dist/index.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { isEnabled, resolveConfig } from "./config.js";
-import { currentDistinctId, currentRunId, currentSessionId, setDistinctId, } from "./context.js";
+import { currentDistinctId, currentTurnId, currentSessionId, setDistinctId, } from "./context.js";
 import { coerceProperties } from "./properties.js";
 import { HttpEventSink, getEventSink, resetSink, setEventSink } from "./sink.js";
 import { nowNs } from "./time.js";
@@ -28,7 +28,7 @@ export function init(overrides) {
     }
 }
 /**
- * Emit a product event, stamped with the ambient run-correlation ids (bound by
+ * Emit a product event, stamped with the ambient turn-correlation ids (bound by
  * trace()). Mints an idempotency event_uuid and a call-site timestamp, and
  * sanitizes properties to wire-safe scalars. Fail-open: never throws.
  */
@@ -38,7 +38,7 @@ export function capture(eventName, properties) {
             event_uuid: randomUUID(),
             event_name: eventName,
             distinct_id: currentDistinctId(),
-            run_id: currentRunId(),
+            turn_id: currentTurnId(),
             session_id: currentSessionId(),
             trace_id: "", // populated only if a TS OTel span integration is added later
             timestamp_ns: nowNs(),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "neosigma-sdk",
-  "version": "0.1.0",
-  "description": "NeoSigma TypeScript SDK: emit product events that join your agent traces on run_id.",
+  "version": "0.2.0",
+  "description": "NeoSigma TypeScript SDK: emit product events that join your agent traces on turn_id.",
   "license": "MIT",
   "homepage": "https://www.neosigma.ai",
   "repository": {