@korasafe/trace

Capture agent chain-of-thought (plan, LLM calls, tool calls, reasoning, human approvals) and ship them to the KoraSafe audit log.

Install

npm install @korasafe/trace

Configure

Generate an API key in KoraSafe under Settings → API keys (requires write scope). Then set:

export KORASAFE_API_KEY=sk-live-...

Or pass it directly to KoraTrace.init({ apiKey: '...' }).

10-line example

import { KoraTrace } from '@korasafe/trace';

KoraTrace.init();

await KoraTrace.run('classify_claim', async () => {
  KoraTrace.plan({ steps: ['look up policy', 'score risk', 'route'] });
  KoraTrace.llmCall({ provider: 'openai', model: 'gpt-4o', input: 'claim text', output: 'tier=gold', input_tokens: 120, output_tokens: 30 });
  KoraTrace.toolCall({ name: 'policy_lookup', parameters: { id: 'pol-7' }, response: { tier: 'gold' }, status: 'ok' });
  KoraTrace.humanApproval({ reviewerId: 'user-42', decision: 'approved' });
});

await KoraTrace.flush();

Events appear in the KoraSafe audit log within 5 seconds.

API

`KoraTrace.init(options?)`

Option	Default	Description
`apiKey`	`KORASAFE_API_KEY` env	API key with `write` or `admin` scope
`endpoint`	`KORASAFE_INGEST_URL` env or `https://app.korasafe.ai/api/ingest`	Ingest URL
`batchSize`	`10`	Flush after N events
`flushIntervalMs`	`5000`	Flush after this many ms of buffered events
`timeoutMs`	`10000`	Per-request HTTP timeout
`maxRetries`	`3`	Retry count on 5xx and network errors
`disabled`	`false`	Drop all events; useful for tests

`KoraTrace.run(taskName, fn)`

Wrap an agent loop. Emits run_start + run_end events with a shared trace_id, opens an async context so nested plan / llmCall / toolCall / humanApproval calls auto-attach to the same trace. Returns whatever fn returns. Surfaces thrown errors with an error run_end event before rethrowing.

`KoraTrace.plan({ steps, reasoning? })`

Log the initial plan. steps can be strings or { step, description, expected_outcome? } objects.

`KoraTrace.llmCall({ provider, model, input, output, input_tokens?, output_tokens?, total_tokens?, cost_usd?, duration_ms?, status?, error? })`

Log an LLM invocation. Tokens auto-sum if total_tokens is omitted.

`KoraTrace.toolCall({ name, parameters?, response?, status?, duration_ms?, error? })`

Log a tool or external API call.

`KoraTrace.humanApproval({ reviewerId, decision, notes?, approvalChain? })`

Log a human-in-the-loop decision. decision is approved, rejected, or escalated.

`KoraTrace.flush()`

Force-flush buffered events. Resolves after the in-flight HTTP request completes.

`KoraTrace.shutdown()`

Close the SDK. Flushes any buffered events. Use in test teardown or graceful shutdown.

Notes

Batches by event count (batchSize) and time (flushIntervalMs), whichever hits first.
Retries 5xx and network errors with exponential backoff + jitter. 4xx errors throw immediately.
All event emissions are synchronous and non-blocking; the HTTP work happens out-of-band.
Calling plan / llmCall / toolCall / humanApproval outside a run() block throws. Wrap your agent loop or call them after KoraTrace.run(...).
The SDK uses AsyncLocalStorage for trace context propagation across await boundaries. Node 18+.

License

MIT