@warpmetrics/warp 0.0.18 → 0.0.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpmetrics/warp",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "description": "Measure your agents, not your LLM calls.",
   "type": "module",
   "main": "src/index.js",

package/src/core/reserve.js

@@ -0,0 +1,43 @@
+// Warpmetrics SDK — reserve()
+
+import { generateId } from './utils.js';
+import { actRegistry, runRegistry, groupRegistry, outcomeRegistry } from './registry.js';
+
+/**
+ * Reserve an event ID without queueing.
+ *
+ * Takes a descriptor (returned by calling an event function without its
+ * required target) and assigns a pre-generated ID.  The ID is registered
+ * as a stub so that ref() can resolve it immediately.
+ *
+ * @param {{ _descriptor: true, _eventType: string, name: string, opts: Record<string, any> | null }} descriptor
+ * @returns {Readonly<{ id: string, _type: string, name: string, opts: Record<string, any> | null }>}
+ */
+export function reserve(descriptor) {
+  if (!descriptor || !descriptor._descriptor) {
+    throw new Error('reserve() requires a descriptor from act(), run(), etc.');
+  }
+
+  const prefixMap = { act: 'act', run: 'run', group: 'grp', outcome: 'oc' };
+  const prefix = prefixMap[descriptor._eventType];
+  if (!prefix) {
+    throw new Error(`reserve() — unknown event type: ${descriptor._eventType}`);
+  }
+
+  const id = generateId(prefix);
+
+  // Register as stub so ref() can resolve it
+  const registryMap = { act: actRegistry, run: runRegistry, group: groupRegistry, outcome: outcomeRegistry };
+  const registry = registryMap[descriptor._eventType];
+  if (!registry) {
+    throw new Error(`reserve() — no registry for event type: ${descriptor._eventType}`);
+  }
+  registry.set(id, { ...(registry.get(id) || {}), id, stub: true });
+
+  return Object.freeze({
+    id,
+    _type: descriptor._eventType,
+    name: descriptor.name,
+    opts: descriptor.opts,
+  });
+}

package/src/core/transport.js

@@ -166,7 +166,7 @@ export function logRun(data) {
     label: data.label,
     opts: data.opts || null,
     refId: data.refId || null,
-    timestamp: new Date().toISOString(),
+    startedAt: data.startedAt || new Date().toISOString(),
   });
 }
 
@@ -175,7 +175,7 @@ export function logGroup(data) {
     id: data.id,
     label: data.label,
     opts: data.opts || null,
-    timestamp: new Date().toISOString(),
+    startedAt: data.startedAt || new Date().toISOString(),
   });
 }
 

package/src/core/warp.js

@@ -32,13 +32,14 @@ function createInterceptor(originalFn, context, provider) {
 
     try {
       const result  = await originalFn.apply(context, args);
-      const latency = Date.now() - start;
+      const duration = Date.now() - start;
 
       if (stream) {
         return wrapStream(result, { callId, provider, model, messages, tools, start });
       }
 
       const ext  = provider.extract(result);
+      const endedAt = new Date().toISOString();
 
       responseRegistry.set(result, {
         id: callId,
@@ -47,8 +48,9 @@ function createInterceptor(originalFn, context, provider) {
           response: ext.response,
           tools: tools ? tools.map(t => t.function?.name || t.name).filter(Boolean) : null,
           toolCalls: ext.toolCalls,
-          tokens: ext.tokens, latency,
-          timestamp: new Date().toISOString(),
+          tokens: ext.tokens, duration,
+          startedAt: new Date(start).toISOString(),
+          endedAt,
           status: 'success',
         },
       });
@@ -56,13 +58,15 @@ function createInterceptor(originalFn, context, provider) {
       return result;
     } catch (error) {
       const errorResult = { _warpError: true };
+      const duration = Date.now() - start;
       responseRegistry.set(errorResult, {
         id: callId,
         data: {
           id: callId, provider: provider.name, model, messages,
           error: error.message,
-          latency: Date.now() - start,
-          timestamp: new Date().toISOString(),
+          duration,
+          startedAt: new Date(start).toISOString(),
+          endedAt: new Date().toISOString(),
           status: 'error',
         },
       });
@@ -95,6 +99,7 @@ function wrapStream(stream, ctx) {
         ? ctx.provider.normalizeUsage(usage)
         : { prompt: 0, completion: 0, total: 0 };
 
+      const duration = Date.now() - ctx.start;
       responseRegistry.set(wrapped, {
         id: ctx.callId,
         data: {
@@ -102,8 +107,9 @@ function wrapStream(stream, ctx) {
           response: content,
           tools: ctx.tools ? ctx.tools.map(t => t.function?.name || t.name).filter(Boolean) : null,
           tokens,
-          latency: Date.now() - ctx.start,
-          timestamp: new Date().toISOString(),
+          duration,
+          startedAt: new Date(ctx.start).toISOString(),
+          endedAt: new Date().toISOString(),
           status: 'success',
         },
       });

package/src/index.d.ts

@@ -29,6 +29,22 @@ export interface Act {
   readonly _type: 'act';
 }
 
+/** Descriptor returned by event functions called without a target. */
+export interface Descriptor<T extends string> {
+  readonly _descriptor: true;
+  readonly _eventType: T;
+  readonly name: string;
+  readonly opts: Record<string, any> | null;
+}
+
+/** Reserved event handle with pre-generated ID. */
+export interface ReservedAct {
+  readonly id: string;
+  readonly _type: 'act';
+  readonly name: string;
+  readonly opts: Record<string, any> | null;
+}
+
 
 /**
  * Wrap an LLM client to automatically track every API call.
@@ -63,9 +79,11 @@ export interface TraceData {
   /** Token usage. */
   tokens?: { prompt?: number; completion?: number; total?: number };
   /** Duration in milliseconds. */
-  latency?: number;
-  /** ISO 8601 timestamp (auto-generated if omitted). */
-  timestamp?: string;
+  duration?: number;
+  /** ISO 8601 timestamp of when the call started. */
+  startedAt?: string;
+  /** ISO 8601 timestamp of when the call ended (auto-generated if omitted). */
+  endedAt?: string;
   /** "success" (default) or "error". */
   status?: string;
   /** Error message. */
@@ -98,6 +116,19 @@ export function act(
   opts?: Record<string, any>,
 ): Act | undefined;
 
+/** Create an act descriptor (no outcome yet). Pass to reserve() to get an ID. */
+export function act(name: string, opts?: Record<string, any>): Descriptor<'act'>;
+
+/** Complete a reserved act by providing the outcome. */
+export function act(
+  target: Outcome | string,
+  reserved: ReservedAct,
+  opts?: Record<string, any>,
+): Act | undefined;
+
+/** Reserve an event ID without queueing. Returns a handle with pre-generated ID. */
+export function reserve(descriptor: Descriptor<'act'>): ReservedAct;
+
 /** Resolve any trackable target to its string ID. */
 export function ref(target: Run | Group | Act | Outcome | object | string): string | undefined;
 

package/src/index.js

@@ -9,6 +9,8 @@
 //   trace(target, data)              — manually trace a call (non-SDK tools)
 //   outcome(target, name, opts?)     — record a result
 //   act(target, name, opts?)         — record an action, returns act ref
+//   act(name, opts?)                 — create an act descriptor (no queue)
+//   reserve(descriptor)              — reserve an event ID without queueing
 //   ref(target)                      — get tracking ID
 export { warp } from './core/warp.js';
 export { run } from './trace/run.js';
@@ -17,5 +19,6 @@ export { call } from './trace/call.js';
 export { trace } from './trace/trace.js';
 export { outcome } from './trace/outcome.js';
 export { act } from './trace/act.js';
+export { reserve } from './core/reserve.js';
 export { ref } from './trace/ref.js';
 export { flush } from './core/transport.js';

package/src/trace/act.js

@@ -8,12 +8,51 @@ import { logAct, getConfig } from '../core/transport.js';
 /**
  * Record an action taken on an outcome (e.g. acting on feedback).
  *
- * @param {{ id: string, _type: 'outcome' } | string} target — Outcome handle from outcome(), or outcome ref string (wm_oc_*)
- * @param {string} name            — action name ("Improve Section", "Refine Prompt")
+ * Three modes:
+ *
+ * 1. Normal:     act(outcome, name, opts?)     — queue an act event
+ * 2. Descriptor: act(name, opts?)              — return a descriptor (no queue)
+ * 3. Reserved:   act(outcome, reserved, opts?) — complete a reserved act
+ *
+ * @param {{ id: string, _type: 'outcome' } | string} target
+ * @param {string | { id: string, _type: 'act', name: string, opts: any }} nameOrReserved
  * @param {Record<string, any>} [opts]
- * @returns {{ readonly id: string, readonly _type: 'act' } | undefined}
+ * @returns {{ readonly id: string, readonly _type: 'act' } | { _descriptor: true, _eventType: 'act', name: string, opts: any } | undefined}
  */
-export function act(target, name, opts) {
+export function act(target, nameOrReserved, opts) {
+  // Path A — Descriptor mode: act(name) or act(name, opts)
+  // First arg is a string that doesn't look like a wm_ ref
+  if (typeof target === 'string' && !target.startsWith('wm_')) {
+    return { _descriptor: true, _eventType: 'act', name: target, opts: nameOrReserved || null };
+  }
+
+  // Path B — Complete a reserved act: act(outcome, reserved, extraOpts?)
+  if (nameOrReserved && typeof nameOrReserved === 'object' && nameOrReserved._type === 'act' && nameOrReserved.id) {
+    const refId = getRef(target);
+
+    if (!refId) {
+      if (getConfig().debug) console.warn('[warpmetrics] act() — target not tracked.');
+      return undefined;
+    }
+
+    if (!refId.startsWith('wm_oc_')) {
+      if (getConfig().debug) console.warn('[warpmetrics] act() — target must be an outcome (wm_oc_*).');
+      return undefined;
+    }
+
+    const id = nameOrReserved.id;
+    const mergedOpts = opts
+      ? { ...(nameOrReserved.opts || {}), ...opts }
+      : (nameOrReserved.opts || null);
+
+    const existing = actRegistry.get(id) || {};
+    actRegistry.set(id, { ...existing, id, refId });
+    logAct({ id, refId, name: nameOrReserved.name, opts: mergedOpts });
+
+    return Object.freeze({ id, _type: 'act' });
+  }
+
+  // Path C — Normal: act(outcome, name, opts?)
   const refId = getRef(target);
 
   if (!refId) {
@@ -29,7 +68,7 @@ export function act(target, name, opts) {
   const id = generateId('act');
   actRegistry.set(id, { id, refId });
 
-  logAct({ id, refId, name, opts: opts || null });
+  logAct({ id, refId, name: nameOrReserved, opts: opts || null });
 
   return Object.freeze({ id, _type: 'act' });
 }

package/src/trace/group.js

@@ -14,6 +14,7 @@ import { logGroup, logLink, getConfig } from '../core/transport.js';
  * @returns {{ readonly id: string, readonly _type: 'group' }}
  */
 export function group(target, label, opts) {
+  const startedAt = new Date().toISOString();
   const targetId = getRef(target);
   if (!targetId) {
     if (getConfig().debug) console.warn('[warpmetrics] group() — target not recognised.');
@@ -29,6 +30,7 @@ export function group(target, label, opts) {
     label,
     opts: opts || null,
     parentId: targetId,
+    startedAt,
     groups: [],
     calls: [],
   };

package/src/trace/run.js

@@ -14,6 +14,7 @@ import { logRun, getConfig } from '../core/transport.js';
  * @returns {{ readonly id: string, readonly _type: 'run' }}
  */
 export function run(labelOrRef, labelOrOpts, maybeOpts) {
+  const startedAt = new Date().toISOString();
   let refId = null;
   let label, opts;
 
@@ -37,6 +38,7 @@ export function run(labelOrRef, labelOrOpts, maybeOpts) {
     label,
     opts,
     refId,
+    startedAt,
     groups: [],
     calls: [],
   };

package/src/trace/trace.js

@@ -26,6 +26,10 @@ export function trace(target, data) {
 
   const id = generateId('call');
 
+  const endedAt = data.endedAt || data.timestamp || new Date().toISOString();
+  const duration = data.duration ?? data.latency ?? null;
+  const startedAt = data.startedAt || (duration != null ? new Date(new Date(endedAt).getTime() - duration).toISOString() : endedAt);
+
   const event = {
     id,
     provider: data.provider,
@@ -35,8 +39,9 @@ export function trace(target, data) {
     tools: data.tools || null,
     toolCalls: data.toolCalls || null,
     tokens: data.tokens || null,
-    latency: data.latency ?? null,
-    timestamp: data.timestamp || new Date().toISOString(),
+    duration,
+    startedAt,
+    endedAt,
     status: data.status || 'success',
   };