Cost attribution & custom dimensions

// Hierarchical agents: a supervisor delegates to workers, which may spawn
// their own sub-workers. Nest spans and the tree builds itself: each span
// links to its caller, recursion included, and parallel branches under
// Promise.all parent correctly because context is async-local.
const openai = bear.wrap(new OpenAI());

async function runAgent(name: string, task: Task): Promise<Result> {
  return bear.withSpan(name, { agentId: name, kind: 'agent' }, async () => {
    const plan = await openai.chat.completions.create(planFor(task)); // tracked, tree-linked
    const results = await Promise.all(
      delegationsIn(plan).map((t) => runAgent(t.agent, t)) // children of THIS span
    );
    return synthesize(plan, results);
  });
}

await bear.withSpan('deep-research', {
  workflowId: 'deep-research',
  outcome: 'report_delivered',
  budget: { usd: 2.0, onExceeded: 'throw' }, // the whole tree stops at $2
}, () => runAgent('supervisor', rootTask));

// No spans available at a call site? track() accepts the tree fields
// directly: sessionId, spanId, parentSpanId. Same wire, manual edges.

// One resolution usually runs SEVERAL AI calls (triage, retrieval, drafting),
// often across multiple agents. Wrap the resolution in a SPAN: every call
// made inside it (through your wrapped client) shares one session
// automatically, and the outcome is counted exactly once when the span
// completes. No trace id to mint, no terminal call to remember, no way to
// overcount. If the run throws, the outcome is NOT counted but every dollar
// spent inside is still attributed, so failed work stays visible.
const openai = bear.wrap(new OpenAI()); // wrap once, at startup

await bear.withSpan('resolve-ticket', {
  workflowId: 'ticket-triage',     // the workflow TYPE (constant across runs)
  sessionType: 'ticket',
  outcome: 'ticket_resolved',      // the denominator, counted structurally
}, async () => {
  await bear.withSpan('retriever', { agentId: 'retriever' }, async () => {
    await openai.chat.completions.create(/* ... */); // tracked + tree-linked
  });
  await bear.withSpan('drafter', { agentId: 'drafter' }, async () => {
    await openai.chat.completions.create(/* ... */);
  });
});

// Numerator and denominator in ONE query. Because cost and outcomes live on
// the same unit of work, the platform computes cost per outcome natively,
// with failed units side by side instead of hiding inside the averages.
const perOutcome = await bear.costs.byOutcome({ lastDays: 30 });
const resolved = perOutcome.items.find((o) => o.outcome === 'ticket_resolved');

// TRUE COGS per resolved ticket: full multi-agent cost / resolutions.
// Not cost per token, and not the cost of a single call.
console.log(resolved.completed_count, resolved.cost_per_completed_unit);
// -> 412 0.94   (each resolved ticket cost $0.94 of AI spend, all agents in)

// The number the observability tools cannot show you: what failure costs.
console.log(resolved.failed_count, resolved.failed_cost);
// -> 31 47.10   (31 runs burned $47.10 and resolved nothing)

// Drill into one expensive run: the full call tree, cost per branch.
const tree = await bear.attribution.sessionTree(sessionId);
tree.roots.forEach((n) => console.log(n.name, n.own_cost, n.subtree_cost));

// Tag calls made while building a feature.
bear.track(response, {
  feature: 'search-rerank',
  metadata: {
    environment: 'dev',      // isolate development spend from production
    git_pr: '1421',          // the PR this work landed in
    git_branch: 'feat/rerank',
    developer: 'alice',
  },
});

// Cost of building each feature, in development only.
const byFeature = await bear.attribution.byDimension({
  dimension: 'feature',
  filterKey: 'environment',
  filterValue: 'dev',
  lastDays: 30,
});

// Cost attributable to each merged PR, or each developer.
const byPr = await bear.attribution.byDimension({ dimension: 'git_pr', lastDays: 30 });
const byDeveloper = await bear.attribution.byDimension({ dimension: 'developer', lastDays: 30 });

// Cost per workflow TYPE (every run of each workflow, all agents inside it).
// lastDays resolves client-side to a trailing window; absolute dates still
// work for a fixed period: byWorkflow({ startDate: '2026-01-01', endDate: '2026-01-31' }).
const byWorkflow = await bear.costs.byWorkflow({ lastDays: 30 });

// Cost per AGENT, within or across workflows.
const byAgent = await bear.costs.byAgent({ lastDays: 30 });

// Per-RUN cost: each session is one run/trace. sessions() returns each
// run's total (summed over all its calls); sessionDetail() lists a single
// run call-by-call; sessionTree() reconstructs its call tree with
// per-branch roll-ups.
const runs = await bear.attribution.sessions({ lastDays: 7 });
runs.sessions.forEach((s) => console.log(s.session_id, s.total_cost, s.event_count));