@warpmetrics/warp 0.0.19 → 0.0.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpmetrics/warp",
-  "version": "0.0.19",
+  "version": "0.0.21",
   "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/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.
@@ -100,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/providers/anthropic.js

@@ -15,7 +15,7 @@ export function extract(result) {
     response: Array.isArray(result?.content)
       ? result.content.filter(c => c.type === 'text').map(c => c.text).join('')
       : '',
-    tokens: { prompt: input, completion: output, total: input + output, cacheWrite, cacheRead },
+    tokens: { prompt: input + cacheWrite + cacheRead, completion: output, total: input + output + cacheWrite + cacheRead, cacheWrite, cacheRead },
     toolCalls: null,
   };
 }
@@ -38,7 +38,7 @@ export function normalizeUsage(usage) {
   const completion = usage?.output_tokens || 0;
   const cacheWrite = usage?.cache_creation_input_tokens || 0;
   const cacheRead  = usage?.cache_read_input_tokens || 0;
-  return { prompt, completion, total: prompt + completion, cacheWrite, cacheRead };
+  return { prompt: prompt + cacheWrite + cacheRead, completion, total: prompt + completion + cacheWrite + cacheRead, cacheWrite, cacheRead };
 }
 
 export function proxy(client, intercept) {

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' });
 }