@warpmetrics/warp 0.0.2

package/src/trace/outcome.js

@@ -0,0 +1,33 @@
+// Warpmetrics SDK — outcome()
+
+import { ref as getRef } from './ref.js';
+import { logOutcome, getConfig } from '../core/transport.js';
+
+/**
+ * Record an outcome on any tracked target.
+ *
+ * @param {object | string} target — Run, Group, LLM response, or ref string
+ * @param {string} name            — outcome name ("completed", "failed", "helpful")
+ * @param {object} [options]
+ * @param {string} [options.reason]            — why this outcome occurred
+ * @param {string} [options.source]            — who / what recorded it
+ * @param {string[]} [options.tags]            — categorisation tags
+ * @param {Record<string, any>} [options.metadata] — arbitrary extra data
+ */
+export function outcome(target, name, options = {}) {
+  const targetId = getRef(target);
+
+  if (!targetId) {
+    if (getConfig().debug) console.warn('[warpmetrics] outcome() — target not tracked.');
+    return;
+  }
+
+  logOutcome({
+    targetId,
+    name,
+    reason:   options.reason   || null,
+    source:   options.source   || null,
+    tags:     options.tags     || null,
+    metadata: options.metadata || null,
+  });
+}

package/src/trace/outcome.test.js

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest';
+import { warp, run, outcome, flush } from '../index.js';
+import { setupBeforeEach, createMockOpenAI, OPENAI_RESPONSE } from '../../test/setup.js';
+
+setupBeforeEach();
+
+describe('outcome()', () => {
+  it('enqueues an outcome event for a run', async () => {
+    const r = run('test');
+    outcome(r, 'completed', { reason: 'All good' });
+    await flush();
+
+    const body = JSON.parse(global.fetch.mock.calls[0][1].body);
+    const o = body.outcomes.find(e => e.name === 'completed');
+    expect(o).toBeDefined();
+    expect(o.targetId).toBe(r.id);
+    expect(o.reason).toBe('All good');
+  });
+
+  it('works with a ref string', async () => {
+    outcome('wm_run_abc123', 'shipped');
+    await flush();
+
+    const body = JSON.parse(global.fetch.mock.calls[0][1].body);
+    expect(body.outcomes[0].targetId).toBe('wm_run_abc123');
+  });
+
+  it('works on an LLM response', async () => {
+    const client = createMockOpenAI(OPENAI_RESPONSE);
+    const wrapped = warp(client);
+    const response = await wrapped.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
+
+    outcome(response, 'helpful');
+    await flush();
+
+    const body = JSON.parse(global.fetch.mock.calls[0][1].body);
+    const o = body.outcomes.find(e => e.name === 'helpful');
+    expect(o.targetId).toMatch(/^wm_call_/);
+  });
+});

package/src/trace/ref.js

@@ -0,0 +1,27 @@
+// Warpmetrics SDK — ref()
+
+import { responseRegistry } from '../core/registry.js';
+
+/**
+ * Resolve any trackable target to its string ID.
+ *
+ * Accepts:
+ *  - A string ref (pass-through)
+ *  - A Run or Group object  ({ id, _type })
+ *  - An LLM response object (looked up in the response registry)
+ *
+ * @param {object | string} target
+ * @returns {string | undefined}
+ */
+export function ref(target) {
+  if (typeof target === 'string') return target;
+
+  if (target && target._type && target.id) return target.id;
+
+  if (target && typeof target === 'object') {
+    const callId = responseRegistry.get(target);
+    if (callId) return callId;
+  }
+
+  return undefined;
+}

package/src/trace/ref.test.js

@@ -0,0 +1,35 @@
+import { describe, it, expect } from 'vitest';
+import { warp, run, group, ref } from '../index.js';
+import { setupBeforeEach, createMockOpenAI, OPENAI_RESPONSE } from '../../test/setup.js';
+
+setupBeforeEach();
+
+describe('ref()', () => {
+  it('passes through strings', () => {
+    expect(ref('wm_run_abc')).toBe('wm_run_abc');
+  });
+
+  it('extracts id from Run', () => {
+    const r = run('test');
+    expect(ref(r)).toBe(r.id);
+  });
+
+  it('extracts id from Group', () => {
+    const g = group('test');
+    expect(ref(g)).toBe(g.id);
+  });
+
+  it('resolves LLM response to call id', async () => {
+    const client = createMockOpenAI(OPENAI_RESPONSE);
+    const wrapped = warp(client);
+    const response = await wrapped.chat.completions.create({ model: 'gpt-4o-mini', messages: [] });
+
+    const id = ref(response);
+    expect(id).toMatch(/^wm_call_/);
+  });
+
+  it('returns undefined for unknown objects', () => {
+    expect(ref({})).toBeUndefined();
+    expect(ref(null)).toBeUndefined();
+  });
+});

package/src/trace/run.js

@@ -0,0 +1,32 @@
+// Warpmetrics SDK — run()
+
+import { generateId } from '../core/utils.js';
+import { runRegistry } from '../core/registry.js';
+import { logRun } 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
+ * @returns {{ readonly id: string, readonly _type: 'run' }}
+ */
+export function run(label, options = {}) {
+  const id = generateId('run');
+
+  const data = {
+    id,
+    label,
+    link: options.link || null,
+    name: options.name || null,
+    groups: [],
+    calls: [],
+  };
+
+  runRegistry.set(id, data);
+  logRun(data);
+
+  return Object.freeze({ id, _type: 'run' });
+}

package/src/trace/run.test.js

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest';
+import { run, flush } from '../index.js';
+import { runRegistry } from '../core/registry.js';
+import { setupBeforeEach } from '../../test/setup.js';
+
+setupBeforeEach();
+
+describe('run()', () => {
+  it('returns a frozen object with id and _type', () => {
+    const r = run('code-review');
+    expect(r.id).toMatch(/^wm_run_/);
+    expect(r._type).toBe('run');
+    expect(Object.isFrozen(r)).toBe(true);
+  });
+
+  it('stores data in runRegistry', () => {
+    const r = run('code-review', { name: 'PR #42', link: 'https://github.com/pr/42' });
+    const data = runRegistry.get(r.id);
+    expect(data.label).toBe('code-review');
+    expect(data.name).toBe('PR #42');
+    expect(data.link).toBe('https://github.com/pr/42');
+    expect(data.groups).toEqual([]);
+    expect(data.calls).toEqual([]);
+  });
+
+  it('enqueues a run event for transport', async () => {
+    run('test-label');
+    await flush();
+    expect(global.fetch).toHaveBeenCalledTimes(1);
+    const body = JSON.parse(global.fetch.mock.calls[0][1].body);
+    expect(body.runs).toHaveLength(1);
+    expect(body.runs[0].label).toBe('test-label');
+  });
+});