ID & trace helpers

TS · 11

The ID helpers return prefixed ULIDs (via the ulid dependency) that sort lexicographically by creation time. The trace helpers expose the ambient task context the SDK uses for automatic trace attribution - the TS analogue of Python’s ContextVar-based ambient_trace().

import { newTraceId, newEventId, newEngramId } from "@cosmonapse/sdk";

const trace = newTraceId();    // "trc_01JV…"  prefixed ULID
const id    = newEventId();    // "evt_01JV…"  prefixed ULID
const eng   = newEngramId();   // "eng_01JV…"  prefixed ULID (Engram entries)

import { ambientTrace, runWithTraceContext } from "@cosmonapse/sdk";

// Ambient trace context (trace-context.ts): the (traceId, parentId) of
// the TASK currently being handled, carried via AsyncLocalStorage. Code
// running inside a task without explicit trace plumbing  -  e.g. an
// imprint fired from a detectsOutput hook  -  inherits the task's trace.
const ctx = ambientTrace();        // [traceId, parentId] | null
runWithTraceContext(traceId, parentId, () => handler(sig));

Have a feature in mind?

The protocol, SDKs, and CLI are still pre-1.0. If something here is missing, ambiguous, or wrong - open an issue and propose a change. Every breaking change is debated in DECISIONS.md first.

Run the quickstart →Re-read the envelope spec