@50arms/session-telemetry 0.0.0-stage → 0.1.66

package/dist/api-tool-names.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The names a dashboard API tool call can carry in a transcript: a leaf module, because `claim-tracker.ts` and `real-work.ts` both read it and each is
+ * reached from the other through `usage-ledger.ts`.
+ */
+/** The server key a dispatched worker's clean-room config names, and the 50arms plugin's, which an operator session's sub-agent calls: the current prefixes. */
+export declare const CURRENT_API_SERVER_PREFIXES: readonly string[];
+/** The prefixes of the server keys this product no longer uses, still held by older sessions and by stored transcripts. DX-6864 removes them. */
+export declare const RETIRED_API_SERVER_PREFIXES: readonly string[];
+/** Every server prefix a dashboard API tool name can start with. */
+export declare const API_SERVER_PREFIXES: readonly string[];
+/** The generic API tool, by its current name and by the name every release serves until DX-6864 removes it. */
+export declare const API_TOOL_BASE_NAMES: readonly string[];

package/dist/api-tool-names.js

@@ -0,0 +1,19 @@
+/**
+ * The names a dashboard API tool call can carry in a transcript: a leaf module, because `claim-tracker.ts` and `real-work.ts` both read it and each is
+ * reached from the other through `usage-ledger.ts`.
+ */
+// DX-4578: these names are live, none a fallback. A dispatched worker's clean-room config names the server `platform` (DX-6847; it was `danx-dashboard`); an
+// operator session's sub-agent reaches it through the 50arms plugin's server (`plugin:50arms:platform`, tools `mcp__plugin_50arms_platform__*`).
+// DX-6847 / DX-6864 (DEC-571): the server key and the tool name each changed, and a transcript is recognised by what its session called, so every pair a
+// session or a stored transcript can hold is credited until DX-6864 removes the old tool name and the old keys have left every machine:
+//   - the server key `danx-dashboard` of a dispatched worker before DX-6847, the plugin's `plugin_50arms_dashboard` before CP-70, and the pre-DX-6845
+//     plugin's `plugin_danxbot_danx-dashboard` (a session started before either rename still runs that plugin and its tools keep that prefix);
+//   - the tool `danxbot_api`, which every package release up to DX-6864 serves beside `50arms_api`.
+/** The server key a dispatched worker's clean-room config names, and the 50arms plugin's, which an operator session's sub-agent calls: the current prefixes. */
+export const CURRENT_API_SERVER_PREFIXES = ["mcp__platform__", "mcp__plugin_50arms_platform__"];
+/** The prefixes of the server keys this product no longer uses, still held by older sessions and by stored transcripts. DX-6864 removes them. */
+export const RETIRED_API_SERVER_PREFIXES = ["mcp__danx-dashboard__", "mcp__plugin_50arms_dashboard__", "mcp__plugin_danxbot_danx-dashboard__"];
+/** Every server prefix a dashboard API tool name can start with. */
+export const API_SERVER_PREFIXES = [...CURRENT_API_SERVER_PREFIXES, ...RETIRED_API_SERVER_PREFIXES];
+/** The generic API tool, by its current name and by the name every release serves until DX-6864 removes it. */
+export const API_TOOL_BASE_NAMES = ["50arms_api", "danxbot_api"];

package/dist/browser.d.ts

@@ -0,0 +1,29 @@
+/**
+ * DX-2962 — browser-safe subpath (`@50arms/session-telemetry/browser`).
+ *
+ * This file MUST NEVER import a `node:` builtin, directly or transitively —
+ * enforced by `src/__tests__/no-node-imports.test.ts`, which greps every
+ * file this module reaches. `session-log-watcher.ts` (the main entry's
+ * collector) imports `node:fs`/`node:fs/promises`/`node:os`/`node:path`, so
+ * it — and `internal-logger.ts` and `tool-summary.ts`, which it alone pulls
+ * in — are deliberately NOT re-exported here.
+ *
+ * Only the two type-only exports are browser-safe today: `AgentLogEntry` /
+ * `AgentLineage` carry no runtime code at all, so any consumer that needs
+ * to describe a transcript entry's SHAPE (the dashboard server, the
+ * dashboard SPA, a future browser-side usage display) can depend on this
+ * subpath with zero risk of pulling in a Node builtin.
+ *
+ * DX-2963 adds the first real runtime exports here: the one usage counter
+ * (`usage-ledger.ts`) and the one pricing function (`pricing.ts`), both pure
+ * arithmetic with no I/O — `usage-snapshot.ts` in danxbot root (bundled by the
+ * React frontend) imports through THIS subpath, never the main entry.
+ */
+export type { AgentLogEntry, AgentLineage } from "./types.js";
+export { truncStr } from "./tool-summary.js";
+export * from "./usage-ledger.js";
+export * from "./real-work.js";
+export * from "./ledger-timing.js";
+export * from "./transcript-timing.js";
+export * from "./pricing.js";
+export * from "./catalog-prices.js";

package/dist/browser.js

@@ -0,0 +1,10 @@
+// `truncStr` is pure string arithmetic (no `node:` imports, no I/O) — safe
+// to carry on the browser subpath alongside the two types above.
+export { truncStr } from "./tool-summary.js";
+// DX-2963 — counter + pricing (pure arithmetic, no `node:` imports).
+export * from "./usage-ledger.js";
+export * from "./real-work.js";
+export * from "./ledger-timing.js";
+export * from "./transcript-timing.js";
+export * from "./pricing.js";
+export * from "./catalog-prices.js";

package/dist/catalog-prices.d.ts

@@ -0,0 +1,27 @@
+/**
+ * DX-5611 (PLAN-53 G-3) - the ONE builder of the price lookups every pricing function takes, from the model-version catalog's rows
+ * (`model_versions` / `model_version_prices`, as the dashboard answers them). The danxbot server, the bench worker and the MCP's
+ * `subagents-live` all hold the catalog in this shape, so none spells the price fields or the long-prompt pairing again. Pure, no `node:`
+ * imports.
+ */
+import type { PriceCardLookup, PriceLookup } from "./pricing.js";
+/** One `model_version_prices` row: USD per million tokens; `long_prompt_above_tokens` is set exactly on a `long_prompt` row. */
+export interface CatalogPriceRow {
+    speed: string;
+    band: string;
+    input: number;
+    output: number;
+    cache_write_5m: number;
+    cache_write_1h: number;
+    cache_read: number;
+    long_prompt_above_tokens?: number | null;
+}
+/** The part of a declared model version pricing needs. */
+export interface CatalogVersionPrices {
+    model_id: string;
+    prices: readonly CatalogPriceRow[];
+}
+/** The rate cards of every declared version: a speed's `standard` band row is its card, its `long_prompt` band row the second card. */
+export declare function priceCardsOfCatalog(versions: readonly CatalogVersionPrices[]): PriceCardLookup;
+/** The standard-band price of a model at a speed: what a usage bucket (many replies) is priced with. */
+export declare function priceLookupOfCards(cardsOf: PriceCardLookup): PriceLookup;

package/dist/catalog-prices.js

@@ -0,0 +1,31 @@
+const modelPriceOfRow = (p) => ({
+    input: p.input,
+    output: p.output,
+    cacheWrite5m: p.cache_write_5m,
+    cacheWrite1h: p.cache_write_1h,
+    cacheRead: p.cache_read,
+});
+const key = (modelId, speed) => JSON.stringify([modelId, speed]);
+/** The rate cards of every declared version: a speed's `standard` band row is its card, its `long_prompt` band row the second card. */
+export function priceCardsOfCatalog(versions) {
+    const cards = new Map();
+    for (const v of versions) {
+        for (const row of v.prices) {
+            if (row.band !== "standard")
+                continue;
+            const long = v.prices.find((p) => p.speed === row.speed && p.band === "long_prompt");
+            let longPrompt = null;
+            if (long !== undefined) {
+                if (long.long_prompt_above_tokens == null)
+                    throw new Error(`model "${v.model_id}" ${long.speed} long_prompt price row has no long_prompt_above_tokens`);
+                longPrompt = { aboveTokens: long.long_prompt_above_tokens, price: modelPriceOfRow(long) };
+            }
+            cards.set(key(v.model_id, row.speed), { standard: modelPriceOfRow(row), longPrompt });
+        }
+    }
+    return (model, speed) => cards.get(key(model, speed)) ?? null;
+}
+/** The standard-band price of a model at a speed: what a usage bucket (many replies) is priced with. */
+export function priceLookupOfCards(cardsOf) {
+    return (model, speed) => cardsOf(model, speed)?.standard ?? null;
+}

package/dist/claim-tracker.d.ts

@@ -0,0 +1,53 @@
+/** The `50arms_api` tool of a dispatched worker's `platform` server. */
+export declare const DISPATCH_API_TOOL_NAME = "mcp__platform__50arms_api";
+/** Every tool name a sub-agent reaches the dashboard API through. */
+export declare const DASHBOARD_API_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * A card id as the issue routes name it, e.g. `DX-3962`, or an imported card's `DX-3962-IMPORT`, `DX-3962-IMPORT-2`,
+ * `DX-3962-IMPORTED` (DX-6042: the danxbot card-id grammar in src/issues/card-id.ts). Also the wire's validation for
+ * every card id a claim carries.
+ */
+export declare const ISSUE_ID_PATTERN: RegExp;
+/** Longest card id a claim may carry (`dispatches.issue_id` is `VARCHAR(32)`). */
+export declare const ISSUE_ID_MAX_LENGTH = 32;
+/**
+ * Bounds that keep one source's persisted state, and the stats write that carries
+ * it, bounded. A real sub-agent holds one or two cards, so neither is reachable;
+ * the OLDEST entry is the one dropped, because the newest claim is what the next
+ * reply is credited to.
+ */
+export declare const MAX_HELD_CLAIMS = 50;
+export declare const MAX_PENDING_TRANSITIONS = 50;
+/** One transition whose `tool_use` has been read and whose `tool_result` has not. */
+export interface PendingTransition {
+    op: "claim" | "release";
+    issueId: string;
+}
+/** One source's claim state at one transcript position. */
+export interface ClaimState {
+    /** Claimed cards, oldest first. */
+    held: string[];
+    /** In-flight transitions keyed by their `tool_use_id`. */
+    pending: Record<string, PendingTransition>;
+}
+export declare function emptyClaimState(): ClaimState;
+/**
+ * The per-process claim tracker: one state per sub-agent source. Fed every
+ * transcript line by `DispatchUsage` (`operator-bridge` mode only — the worker never
+ * constructs one), seeded from the stored cursor at attach, and snapshotted per
+ * source for the stats write.
+ */
+export declare class ClaimTracker {
+    private readonly states;
+    /** Replace a source's state — at attach (the stored cursor's claims) and on a past-EOF reset (empty). */
+    seed(source: string, state: ClaimState): void;
+    /** A copy of the source's state as of the last line fed; empty for a source that holds nothing. */
+    snapshot(source: string): ClaimState;
+    /** The card a reply whose first line is read NOW is credited to; `null` when the source holds none. */
+    issueFor(source: string): string | null;
+    /** An assistant line's content blocks: remember every claim / release the line asks for until its result arrives. */
+    observeAssistantBlocks(source: string, blocks: readonly unknown[]): void;
+    /** A user line's content blocks: settle every remembered transition whose result is here. */
+    observeResultBlocks(source: string, blocks: readonly unknown[]): void;
+    private stateOf;
+}

package/dist/claim-tracker.js

@@ -0,0 +1,213 @@
+/**
+ * DX-3962 — which card a sub-agent is working, read from the sub-agent's OWN
+ * transcript.
+ *
+ * An operator session builds most cards through sub-agents that claim the card
+ * with a manual `pickup`, which creates no dispatch row. Every such claim is in
+ * the sub-agent's transcript: a `50arms_api` `tool_use`
+ * `POST /api/issues/<ID>/transition {action: "pickup"}` and, later, the
+ * `tool_result` carrying the server's answer. This tracker turns those into the
+ * card id every one of the sub-agent's replies is credited to.
+ *
+ * ## The rule (DX-3962 plan-architecture finding 5)
+ *
+ * Per source, an ORDERED set of claimed cards.
+ *   - a successful `pickup` appends the card, or moves it to the end when it is
+ *     already held;
+ *   - a successful `complete` / `cancel` / `block` / `rollback_pickup` of a held
+ *     card BY THE SAME SOURCE removes it. (`review` is not a transition action —
+ *     Review is a derived status, `issues/derive/status.ts` — so the card's list
+ *     of releases names only the four that exist.)
+ *   - a reply's card is the LAST element of the set at the reply's first line, by
+ *     transcript order, never wall clock. An empty set is `null`.
+ *
+ * Success is read from the RESULT, never the request: a claim or release takes
+ * effect only on the `tool_result` for its own `tool_use_id` whose body is
+ * `{"ok": true, ...}`. A refused pickup (409) never attributes and a refused
+ * release never releases.
+ *
+ * `main` never attributes (epic decision): its replies roll up to the plan or the
+ * board. Quality-gate verdicts, comments and edits are not transitions, so they
+ * never set a claim — a reviewer touching several cards stays unattributed.
+ * Documented unattributed cases: a nested sub-agent with no pickup of its own, and
+ * the reply that issued the pickup call itself (its first line precedes the
+ * successful result).
+ *
+ * ## The state belongs to a transcript position
+ *
+ * The state is the held set PLUS the transitions whose `tool_use` has been read
+ * and whose `tool_result` has not (`pending`). Both are persisted beside the
+ * source's read cursor (`dispatch_source_cursors.claims`): a relay that restarts
+ * resumes at its stored `acked` offset, and a pickup that sits before it is never
+ * re-read, so without the state every later reply would go unattributed. The
+ * pending half closes the narrow window where the restart lands between a pickup's
+ * `tool_use` and its `tool_result`.
+ *
+ * Pure bookkeeping — no `node:` imports, so it rides the browser-safe subpath too.
+ */
+import { API_SERVER_PREFIXES, API_TOOL_BASE_NAMES } from "./api-tool-names.js";
+import { MAIN_SOURCE } from "./usage-ledger.js";
+/** The `50arms_api` tool of a dispatched worker's `platform` server. */
+export const DISPATCH_API_TOOL_NAME = "mcp__platform__50arms_api";
+/** Every tool name a sub-agent reaches the dashboard API through. */
+export const DASHBOARD_API_TOOL_NAMES = new Set(API_SERVER_PREFIXES.flatMap((prefix) => API_TOOL_BASE_NAMES.map((tool) => prefix + tool)));
+/**
+ * A card id as the issue routes name it, e.g. `DX-3962`, or an imported card's `DX-3962-IMPORT`, `DX-3962-IMPORT-2`,
+ * `DX-3962-IMPORTED` (DX-6042: the danxbot card-id grammar in src/issues/card-id.ts). Also the wire's validation for
+ * every card id a claim carries.
+ */
+export const ISSUE_ID_PATTERN = /^[A-Za-z][A-Za-z0-9]*-[0-9]+(?:-IMPORT(?:ED)?(?:-[0-9]+)?)?$/;
+/** Longest card id a claim may carry (`dispatches.issue_id` is `VARCHAR(32)`). */
+export const ISSUE_ID_MAX_LENGTH = 32;
+/** The transition that claims a card. */
+const CLAIM_ACTION = "pickup";
+/** The transitions that end a sub-agent's hold on a card. */
+const RELEASE_ACTIONS = new Set(["complete", "cancel", "block", "rollback_pickup"]);
+// DX-3962: built from ISSUE_ID_PATTERN so the card-id shape lives in one place.
+const TRANSITION_PATH = new RegExp(`^/api/issues/(${ISSUE_ID_PATTERN.source.slice(1, -1)})/transition$`);
+/**
+ * Bounds that keep one source's persisted state, and the stats write that carries
+ * it, bounded. A real sub-agent holds one or two cards, so neither is reachable;
+ * the OLDEST entry is the one dropped, because the newest claim is what the next
+ * reply is credited to.
+ */
+export const MAX_HELD_CLAIMS = 50;
+export const MAX_PENDING_TRANSITIONS = 50;
+export function emptyClaimState() {
+    return { held: [], pending: {} };
+}
+function cloneState(s) {
+    return {
+        held: [...s.held],
+        pending: Object.fromEntries(Object.entries(s.pending).map(([id, p]) => [id, { ...p }])),
+    };
+}
+/** The server's answer to a `50arms_api` call is the JSON text `{"ok": true|false, "status": ...}`; only a leading `ok:true` is a success. */
+const OK_TRUE = /^\s*\{\s*"ok"\s*:\s*true\b/;
+function resultText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((part) => {
+        const p = part;
+        return p !== null && typeof p === "object" && p.type === "text" && typeof p.text === "string" ? p.text : "";
+    })
+        .join("");
+}
+/**
+ * Whether a `tool_result` block reports a successful `50arms_api` call. Anything
+ * that is not a leading `{"ok": true` is NOT a success: an errored tool call, a
+ * 409's `{"ok": false, ...}`, a refusal, text the tool never produces. A truncated
+ * body still starts with its `ok`, so a large answer reads correctly.
+ */
+function resultSucceeded(block) {
+    if (block.is_error === true)
+        return false;
+    return OK_TRUE.test(resultText(block.content));
+}
+/** The transition a `tool_use` block asks for, or `null` when it is not a claim or release of a card. */
+function transitionOf(block) {
+    if (block.type !== "tool_use" || typeof block.name !== "string" || !DASHBOARD_API_TOOL_NAMES.has(block.name))
+        return null;
+    const input = block.input;
+    if (input === null || typeof input !== "object")
+        return null;
+    if (typeof input.method !== "string" || input.method.toUpperCase() !== "POST")
+        return null;
+    if (typeof input.path !== "string")
+        return null;
+    const match = TRANSITION_PATH.exec(input.path);
+    if (match === null)
+        return null;
+    const body = input.body;
+    if (body === null || typeof body !== "object" || typeof body.action !== "string")
+        return null;
+    if (match[1].length > ISSUE_ID_MAX_LENGTH)
+        return null;
+    if (body.action === CLAIM_ACTION)
+        return { op: "claim", issueId: match[1] };
+    if (RELEASE_ACTIONS.has(body.action))
+        return { op: "release", issueId: match[1] };
+    return null;
+}
+/**
+ * The per-process claim tracker: one state per sub-agent source. Fed every
+ * transcript line by `DispatchUsage` (`operator-bridge` mode only — the worker never
+ * constructs one), seeded from the stored cursor at attach, and snapshotted per
+ * source for the stats write.
+ */
+export class ClaimTracker {
+    states = new Map();
+    /** Replace a source's state — at attach (the stored cursor's claims) and on a past-EOF reset (empty). */
+    seed(source, state) {
+        if (source === MAIN_SOURCE)
+            return;
+        this.states.set(source, cloneState(state));
+    }
+    /** A copy of the source's state as of the last line fed; empty for a source that holds nothing. */
+    snapshot(source) {
+        const state = this.states.get(source);
+        return state === undefined ? emptyClaimState() : cloneState(state);
+    }
+    /** The card a reply whose first line is read NOW is credited to; `null` when the source holds none. */
+    issueFor(source) {
+        const held = this.states.get(source)?.held;
+        return held === undefined || held.length === 0 ? null : held[held.length - 1];
+    }
+    /** An assistant line's content blocks: remember every claim / release the line asks for until its result arrives. */
+    observeAssistantBlocks(source, blocks) {
+        if (source === MAIN_SOURCE)
+            return;
+        for (const raw of blocks) {
+            const block = raw;
+            if (block === null || typeof block !== "object" || typeof block.id !== "string")
+                continue;
+            const transition = transitionOf(block);
+            if (transition === null)
+                continue;
+            const state = this.stateOf(source);
+            delete state.pending[block.id];
+            state.pending[block.id] = transition;
+            const ids = Object.keys(state.pending);
+            for (const stale of ids.slice(0, Math.max(0, ids.length - MAX_PENDING_TRANSITIONS)))
+                delete state.pending[stale];
+        }
+    }
+    /** A user line's content blocks: settle every remembered transition whose result is here. */
+    observeResultBlocks(source, blocks) {
+        if (source === MAIN_SOURCE)
+            return;
+        const state = this.states.get(source);
+        if (state === undefined)
+            return;
+        for (const raw of blocks) {
+            const block = raw;
+            if (block === null || typeof block !== "object" || block.type !== "tool_result")
+                continue;
+            if (typeof block.tool_use_id !== "string")
+                continue;
+            const pending = state.pending[block.tool_use_id];
+            if (pending === undefined)
+                continue;
+            delete state.pending[block.tool_use_id];
+            if (!resultSucceeded(block))
+                continue;
+            state.held = state.held.filter((id) => id !== pending.issueId);
+            if (pending.op === "claim") {
+                state.held.push(pending.issueId);
+                if (state.held.length > MAX_HELD_CLAIMS)
+                    state.held = state.held.slice(state.held.length - MAX_HELD_CLAIMS);
+            }
+        }
+    }
+    stateOf(source) {
+        let state = this.states.get(source);
+        if (state === undefined) {
+            state = emptyClaimState();
+            this.states.set(source, state);
+        }
+        return state;
+    }
+}