@warpmetrics/warp 0.0.10 → 0.0.11

package/package.json

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

package/src/core/registry.js

@@ -7,5 +7,8 @@ export const runRegistry = new Map();
 /** @type {Map<string, object>}  group id → group data */
 export const groupRegistry = new Map();
 
+/** @type {Map<string, object>}  act id → act data */
+export const actRegistry = new Map();
+
 /** @type {WeakMap<object, string>}  LLM response object → call id */
 export const responseRegistry = new WeakMap();

package/src/core/transport.js

@@ -159,6 +159,7 @@ export function logRun(data) {
     label: data.label,
     link: data.link,
     name: data.name,
+    refId: data.refId || null,
     timestamp: new Date().toISOString(),
   });
 }
@@ -188,7 +189,7 @@ export function logLink(data) {
 export function logOutcome(data) {
   enqueue('outcomes', {
     id: data.id,
-    targetId: data.targetId,
+    refId: data.refId,
     name: data.name,
     reason: data.reason,
     source: data.source,
@@ -200,7 +201,8 @@ export function logOutcome(data) {
 
 export function logAct(data) {
   enqueue('acts', {
-    targetId: data.targetId,
+    id: data.id,
+    refId: data.refId,
     name: data.name,
     metadata: data.metadata,
     timestamp: new Date().toISOString(),

package/src/core/utils.js

@@ -6,7 +6,7 @@ const ulid = monotonicFactory();
 
 /**
  * Generate a prefixed ULID-based unique ID (lowercase).
- * @param {'run' | 'grp' | 'call' | 'oc'} prefix
+ * @param {'run' | 'grp' | 'call' | 'oc' | 'act'} prefix
  * @returns {string} e.g. "wm_run_01jkx3ndek0gh4r5tmqp9a3bcv"
  */
 export function generateId(prefix) {

package/src/index.d.ts

@@ -47,6 +47,11 @@ export interface OutcomeOptions {
   metadata?: Record<string, any>;
 }
 
+export interface Act {
+  readonly id: string;
+  readonly _type: 'act';
+}
+
 
 /**
  * Wrap an LLM client to automatically track every API call.
@@ -56,6 +61,8 @@ export function warp<T>(client: T, options?: WarpOptions): T;
 
 /** Create a run — the top-level unit that tracks one agent execution. */
 export function run(label: string, options?: RunOptions): Run;
+/** Create a follow-up run from an act. */
+export function run(act: Act | string, label: string, options?: RunOptions): Run;
 
 /** Create a group — a logical phase or step inside a run. */
 export function group(label: string, options?: GroupOptions): Group;
@@ -70,15 +77,15 @@ export function outcome(
   options?: OutcomeOptions,
 ): Outcome | undefined;
 
-/** Record an action taken on an outcome (e.g. acting on feedback). */
+/** Record an action taken on an outcome. Returns an Act handle for use with run(). */
 export function act(
   target: Outcome | string,
   name: string,
   metadata?: Record<string, any>,
-): void;
+): Act | undefined;
 
 /** Resolve any trackable target to its string ID. */
-export function ref(target: Run | Group | Outcome | object | string): string | undefined;
+export function ref(target: Run | Group | Act | Outcome | object | string): string | undefined;
 
 /** Manually flush pending events to the API. */
 export function flush(): Promise<void>;

package/src/index.js

@@ -3,10 +3,11 @@
 //
 //   warp(client, options?)           — wrap an LLM client
 //   run(label, options?)             — create a run
+//   run(act, label, options?)        — create a follow-up run from an act
 //   group(label, options?)           — create a group
 //   add(target, ...items)            — add groups / calls to a run or group
 //   outcome(target, name, options?)  — record a result
-//   act(target, name, options?)      — record an action taken on a result
+//   act(target, name, metadata?)     — record an action, returns act ref
 //   ref(target)                      — get tracking ID
 export { warp } from './core/warp.js';
 export { run } from './trace/run.js';

package/src/trace/act.js

@@ -1,6 +1,8 @@
 // Warpmetrics SDK — act()
 
 import { ref as getRef } from './ref.js';
+import { generateId } from '../core/utils.js';
+import { actRegistry } from '../core/registry.js';
 import { logAct, getConfig } from '../core/transport.js';
 
 /**
@@ -9,23 +11,25 @@ import { logAct, getConfig } from '../core/transport.js';
  * @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")
  * @param {Record<string, any>} [metadata] — arbitrary extra data
+ * @returns {{ readonly id: string, readonly _type: 'act' } | undefined}
  */
 export function act(target, name, metadata) {
-  const targetId = getRef(target);
+  const refId = getRef(target);
 
-  if (!targetId) {
+  if (!refId) {
     if (getConfig().debug) console.warn('[warpmetrics] act() — target not tracked.');
-    return;
+    return undefined;
   }
 
-  if (!targetId.startsWith('wm_oc_')) {
+  if (!refId.startsWith('wm_oc_')) {
     if (getConfig().debug) console.warn('[warpmetrics] act() — target must be an outcome (wm_oc_*).');
-    return;
+    return undefined;
   }
 
-  logAct({
-    targetId,
-    name,
-    metadata: metadata || null,
-  });
+  const id = generateId('act');
+  actRegistry.set(id, { id, refId });
+
+  logAct({ id, refId, name, metadata: metadata || null });
+
+  return Object.freeze({ id, _type: 'act' });
 }

package/src/trace/outcome.js

@@ -19,9 +19,9 @@ import { logOutcome, getConfig } from '../core/transport.js';
  * @returns {{ id: string, _type: 'outcome' } | undefined}
  */
 export function outcome(target, name, options = {}) {
-  const targetId = getRef(target);
+  const refId = getRef(target);
 
-  if (!targetId) {
+  if (!refId) {
     if (getConfig().debug) console.warn('[warpmetrics] outcome() — target not tracked.');
     return undefined;
   }
@@ -30,7 +30,7 @@ export function outcome(target, name, options = {}) {
 
   logOutcome({
     id,
-    targetId,
+    refId,
     name,
     reason:   options.reason   || null,
     source:   options.source   || null,

package/src/trace/run.js

@@ -1,19 +1,37 @@
 // Warpmetrics SDK — run()
 
+import { ref as getRef } from './ref.js';
 import { generateId } from '../core/utils.js';
 import { runRegistry } from '../core/registry.js';
-import { logRun } from '../core/transport.js';
+import { logRun, getConfig } from '../core/transport.js';
 
 /**
  * Create a run — the top-level unit that tracks one agent execution.
  *
- * @param {string} label  — run type used for aggregation ("code-review", "bug-fix")
- * @param {object} [options]
- * @param {string} [options.link]  — external reference ("ticket:PROJ-101", PR URL, etc.)
- * @param {string} [options.name]  — human-readable name
+ * @param {string | { id: string, _type: 'act' }} labelOrRef — run label, or act ref for follow-up runs
+ * @param {string | object} [labelOrOpts] — label (if first arg is act ref) or options
+ * @param {object} [maybeOpts]
+ * @param {string} [maybeOpts.link]  — external reference ("ticket:PROJ-101", PR URL, etc.)
+ * @param {string} [maybeOpts.name]  — human-readable name
  * @returns {{ readonly id: string, readonly _type: 'run' }}
  */
-export function run(label, options = {}) {
+export function run(labelOrRef, labelOrOpts, maybeOpts) {
+  let refId = null;
+  let label, options;
+
+  if (typeof labelOrRef === 'string' && !labelOrRef.startsWith('wm_act_')) {
+    label = labelOrRef;
+    options = labelOrOpts || {};
+  } else {
+    refId = getRef(labelOrRef);
+    if (refId && !refId.startsWith('wm_act_')) {
+      if (getConfig().debug) console.warn('[warpmetrics] run() ref must be an act (wm_act_*).');
+      refId = null;
+    }
+    label = labelOrOpts;
+    options = maybeOpts || {};
+  }
+
   const id = generateId('run');
 
   const data = {
@@ -21,6 +39,7 @@ export function run(label, options = {}) {
     label,
     link: options.link || null,
     name: options.name || null,
+    refId,
     groups: [],
     calls: [],
   };