@hypersoniclabs/helix-cli 0.1.7 → 0.1.24-helix3.438

package/dist/money.js

@@ -0,0 +1,299 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.roundLix = exports.LIX_DP = void 0;
+exports.formatLix = formatLix;
+exports.getLixBalance = getLixBalance;
+exports.formatBalance = formatBalance;
+exports.normalizeQuote = normalizeQuote;
+exports.quoteGeneration = quoteGeneration;
+exports.formatQuote = formatQuote;
+exports.receiptLix = receiptLix;
+exports.formatReceipt = formatReceipt;
+exports.formatWaitState = formatWaitState;
+exports.listJobs = listJobs;
+exports.formatJobs = formatJobs;
+const api_1 = require("./api");
+/** LIX is a decimal amount (the wallet column is numeric(19,4)) — never minor units. */
+exports.LIX_DP = 4;
+const roundLix = (value) => Math.round(value * 10 ** exports.LIX_DP) / 10 ** exports.LIX_DP;
+exports.roundLix = roundLix;
+/** Render a LIX amount for humans: trim trailing zeros but never lie about precision. */
+function formatLix(value) {
+    const rounded = (0, exports.roundLix)(value);
+    return `${Number.isInteger(rounded) ? rounded.toFixed(0) : rounded.toString()} LIX`;
+}
+const num = (value) => {
+    const parsed = typeof value === 'string' ? Number(value) : (value ?? 0);
+    return Number.isFinite(parsed) ? parsed : 0;
+};
+/**
+ * Read the caller's LIX balance.
+ *
+ * Prefers `GET /api/v1/lix-billing/balance`, which reports available/held/total and itemises open
+ * holds. Falls back to the raw economy wallet (`GET /api/v1/wallet/me`) on 404 so the command works
+ * against deployments where the billing route has not landed yet — and says which one answered,
+ * because the wallet has no notion of `held` and reporting 0 held as if it were measured would hide
+ * exactly the stranded money this command exists to reveal.
+ */
+async function getLixBalance(creds) {
+    const api = api_1.HelixApi.forCredentials(creds);
+    try {
+        const res = await api.request('GET', '/api/v1/lix-billing/balance');
+        const available = num(res.available);
+        const held = num(res.held);
+        return {
+            currency: res.currency ?? 'LIX',
+            available,
+            held,
+            total: res.total === undefined ? (0, exports.roundLix)(available + held) : num(res.total),
+            breakdown: res.breakdown,
+            holds: res.holds ?? [],
+            source: 'lix-billing',
+        };
+    }
+    catch (err) {
+        if (!(err instanceof api_1.ApiError) || err.status !== 404)
+            throw err;
+        const wallet = await api.request('GET', '/api/v1/wallet/me');
+        const withdrawable = num(wallet.withdrawable_balance);
+        const nonWithdrawable = num(wallet.non_withdrawable_balance);
+        const available = (0, exports.roundLix)(withdrawable + nonWithdrawable);
+        return {
+            currency: wallet.currency ?? 'LIX',
+            available,
+            held: 0,
+            total: available,
+            breakdown: { withdrawable, nonWithdrawable },
+            holds: [],
+            source: 'wallet',
+        };
+    }
+}
+function formatBalance(balance) {
+    const lines = [
+        `Available  ${formatLix(balance.available)}`,
+        `Held       ${formatLix(balance.held)}${balance.holds.length ? `  (${balance.holds.length} open reservation${balance.holds.length === 1 ? '' : 's'})` : ''}`,
+        `Total      ${formatLix(balance.total)}`,
+    ];
+    if (balance.breakdown) {
+        const { withdrawable, nonWithdrawable } = balance.breakdown;
+        if (withdrawable !== undefined || nonWithdrawable !== undefined) {
+            lines.push(`  of which withdrawable ${formatLix(withdrawable ?? 0)} · non-withdrawable ${formatLix(nonWithdrawable ?? 0)}`);
+        }
+    }
+    if (balance.holds.length) {
+        lines.push('', 'Open holds (LIX escrowed by unfinished jobs):');
+        for (const hold of balance.holds) {
+            const label = hold.label ?? hold.action ?? 'reservation';
+            const job = hold.jobId ? ` job ${hold.jobId}` : '';
+            const until = hold.holdUntil ? ` until ${hold.holdUntil}` : '';
+            lines.push(`  • ${formatLix(hold.lix)}  ${label}${job}${until}`);
+        }
+        lines.push('', '  A hold is money escrowed by a job that never finished. Settle or abandon the job to release it.');
+    }
+    if (balance.source === 'wallet') {
+        // The billing route is live, so a fallback now means it was unreachable for this call rather
+        // than absent from the deployment. Still name the source: a wallet read has no notion of
+        // `held`, and printing 0 as though it were measured hides the stranded money this exists to show.
+        lines.push('', '  • Read from the raw wallet — the balance service did not answer this call, so `Held` is', '    NOT measured here and any open reservations are invisible. Re-run to get the full picture.');
+    }
+    return lines.join('\n');
+}
+// The quote route was renamed from Spark to LIX denomination. Read both keys so one CLI is correct
+// against a deployment on either side of that change rather than silently reporting 0.
+const componentLix = (component) => component.lix ?? component.spark ?? 0;
+function normalizeQuote(res) {
+    const components = res.components ?? [];
+    const totalLix = res.lix ??
+        res.pricing?.totalLix ??
+        res.spark ??
+        res.pricing?.totalSpark ??
+        components.reduce((sum, c) => sum + componentLix(c), 0);
+    const baseLix = res.pricing?.baseLix ??
+        res.pricing?.baseSpark ??
+        components
+            .filter((c) => c.priceType !== 'premium')
+            .reduce((sum, c) => sum + componentLix(c), 0);
+    const premiumLix = res.pricing?.premiumLix ??
+        res.pricing?.premiumSpark ??
+        (0, exports.roundLix)(totalLix - baseLix);
+    // The cap, in preference order: the server's own figure, then the sum of per-component caps,
+    // then the total. Falling back to the total is safe only because a deployment without maxLix is
+    // one where nothing exceeds its quote — the moment a cap exists it is authoritative.
+    const componentMax = components.reduce((sum, c) => sum + (c.maxLix ?? componentLix(c)), 0);
+    const maxLix = res.maxLix ??
+        res.pricing?.maxLix ??
+        (components.length ? componentMax : totalLix);
+    // The weakest guarantee any component makes is the guarantee the whole quote makes.
+    const basis = res.estimateBasis
+        ? res.estimateBasis
+        : components.some((c) => c.estimateBasis === 'estimate')
+            ? 'estimate'
+            : components.some((c) => c.estimateBasis === 'ceiling')
+                ? 'ceiling'
+                : 'exact';
+    return {
+        totalLix: (0, exports.roundLix)(totalLix),
+        baseLix: (0, exports.roundLix)(baseLix),
+        premiumLix: (0, exports.roundLix)(premiumLix),
+        // A cap below the estimate would be nonsense; never report one.
+        maxLix: (0, exports.roundLix)(Math.max(maxLix, totalLix)),
+        components,
+        quoteToken: res.quoteToken,
+        quoteId: res.quoteId,
+        expiresAt: res.expiresAt,
+        configVersion: res.configVersion,
+        estimateBasis: basis,
+    };
+}
+/**
+ * Price a generation BEFORE running it. The request body is the same DTO the generation route
+ * takes, deliberately: it prices the real request rather than a parallel model of it.
+ */
+async function quoteGeneration(creds, input) {
+    return normalizeQuote(await api_1.HelixApi.forCredentials(creds).request('POST', '/api/v1/dreamer/assets/quotes', input));
+}
+function formatQuote(quote, balance) {
+    const lines = ['Estimated cost'];
+    const width = Math.max(...quote.components.map((c) => (c.label ?? c.stage).length), 8);
+    for (const component of quote.components) {
+        const name = (component.label ?? component.stage).padEnd(width);
+        const premium = component.priceType === 'premium' ? '  (premium)' : '';
+        const lix = componentLix(component);
+        // Only worth showing a cap that differs — "0.2 LIX (at most 0.2)" is noise.
+        const cap = component.maxLix !== undefined && (0, exports.roundLix)(component.maxLix) > (0, exports.roundLix)(lix)
+            ? `  (at most ${formatLix(component.maxLix)})`
+            : '';
+        lines.push(`  ${name}  ${formatLix(lix)}${premium}${cap}`);
+    }
+    if (quote.components.length)
+        lines.push(`  ${''.padEnd(width, '─')}  ────────`);
+    lines.push(`  ${'Total'.padEnd(width)}  ${formatLix(quote.totalLix)}`);
+    // Say exactly what the number guarantees. These three are genuinely different promises, and
+    // flattening them is how "you are charged actual usage and refunded the difference" ended up
+    // printed over a job that could be — and was — charged above its quote.
+    const capsAbove = (0, exports.roundLix)(quote.maxLix) > (0, exports.roundLix)(quote.totalLix);
+    if (quote.estimateBasis === 'ceiling') {
+        lines.push('', `  METERED: you are charged actual usage, never more than ${formatLix(quote.maxLix)}.`);
+    }
+    else if (quote.estimateBasis === 'estimate') {
+        lines.push('', '  METERED, and this is an ESTIMATE, not a cap: the provider bills the duration it accepts,', `  which can exceed the one requested. The charge can land above this figure — at most ${formatLix(quote.maxLix)}.`);
+    }
+    else if (capsAbove) {
+        lines.push('', `  The charge can reach ${formatLix(quote.maxLix)}.`);
+    }
+    if (balance) {
+        // Project the WORST case: a balance that covers the estimate but not the cap is a job that can
+        // fail part-way through with money already spent.
+        const after = (0, exports.roundLix)(balance.available - quote.maxLix);
+        lines.push('', `  Balance ${formatLix(balance.available)} available → ${formatLix(after)} after this job` +
+            (capsAbove ? ' at its maximum' : ''));
+        if (after < 0) {
+            lines.push(`  ✖ NOT ENOUGH LIX — short by ${formatLix(Math.abs(after))}.`);
+        }
+    }
+    if (quote.expiresAt)
+        lines.push(`  quote expires ${quote.expiresAt}`);
+    return lines.join('\n');
+}
+// ---- Receipts --------------------------------------------------------------
+/**
+ * What a finished job actually cost, in LIX, from either route.
+ *
+ * Dreamer reports `lixSpentTotal`. The asset pipeline reported `units` and never said LIX, so
+ * nothing on that receipt stated the currency — and `units` IS LIX: the backend computes it as
+ * `Number(job.lixSpentTotal || '0')`, same number, different name, no conversion. Read the
+ * canonical field, fall back to the alias, and present one name.
+ */
+function receiptLix(job) {
+    const raw = job.lixSpentTotal ?? job.units ?? job.sparkSpentTotal;
+    if (raw === undefined || raw === null)
+        return null;
+    const value = typeof raw === 'string' ? Number(raw) : raw;
+    return Number.isFinite(value) ? (0, exports.roundLix)(value) : null;
+}
+/** One consistent cost line for both generation routes. */
+function formatReceipt(job) {
+    const lix = receiptLix(job);
+    if (lix === null)
+        return null;
+    return `Charged ${formatLix(lix)}`;
+}
+/**
+ * How long this job has been working, and what happens if it never finishes.
+ *
+ * A cold end-to-end run watched a music generation sit at `stage: "provider"` with LIX held and
+ * `updatedAt` frozen. Nothing in any payload distinguished "the provider is still composing" from
+ * "the process that was calling the provider is gone", there was no stated deadline, and
+ * `recovery.actions` was empty — so after fifteen minutes the run started the duplicate job the
+ * tools explicitly tell you not to start. (The duplicate returned in ten seconds; the original
+ * later surfaced as failed with no charge, i.e. the platform HAD recovered it — silently, with no
+ * way to know that was coming.)
+ *
+ * The platform's actual contract: an interrupted paid provider call is never repeated, and its
+ * hold is released by bounded automatic reconciliation. That is a good contract. It was just
+ * invisible. Say it, with the elapsed time, so waiting is an informed decision rather than a guess.
+ */
+function formatWaitState(job, now = new Date()) {
+    const TERMINAL = ['published', 'failed', 'succeeded', 'blocked_insufficient_lix'];
+    if (!job.status || TERMINAL.includes(job.status))
+        return null;
+    const stage = job.currentStage;
+    const started = job.stages?.find((s) => s.name === stage)?.startedAt ?? job.updatedAt;
+    if (!started)
+        return null;
+    const elapsedMs = now.getTime() - new Date(started).getTime();
+    if (!Number.isFinite(elapsedMs) || elapsedMs < 0)
+        return null;
+    const minutes = Math.floor(elapsedMs / 60_000);
+    const elapsed = minutes >= 1 ? `${minutes}m` : `${Math.max(1, Math.round(elapsedMs / 1000))}s`;
+    const lines = [`Working for ${elapsed}${stage ? ` (stage: ${stage})` : ''}.`];
+    if (stage === 'provider') {
+        lines.push('  A paid provider call is NEVER repeated automatically. If this attempt was interrupted,', '  HELIX reconciles it on its own and releases the hold — you do not need to do anything,', '  and starting a second job would pay for the same thing twice.');
+    }
+    if (job.openHoldLix) {
+        lines.push(`  ${formatLix(job.openHoldLix)} escrowed while it runs; released on settle, or by the 24h hold sweep.`);
+    }
+    return lines.join('\n');
+}
+async function listJobs(creds, query = {}) {
+    const params = new URLSearchParams();
+    if (query.limit !== undefined)
+        params.set('limit', String(query.limit));
+    if (query.offset !== undefined)
+        params.set('offset', String(query.offset));
+    if (query.state)
+        params.set('state', query.state);
+    const suffix = params.toString() ? `?${params}` : '';
+    const res = await api_1.HelixApi.forCredentials(creds).request('GET', `/api/v1/dreamer/jobs${suffix}`);
+    return {
+        jobs: res.data ?? res.items ?? res.jobs ?? [],
+        total: res.total ?? res.pageInfo?.totalCount ?? null,
+    };
+}
+function formatJobs(result) {
+    if (!result.jobs.length)
+        return 'No generation jobs.';
+    const lines = [];
+    let spent = 0;
+    for (const job of result.jobs) {
+        const lix = receiptLix(job);
+        if (lix)
+            spent += lix;
+        const gate = job.awaitingApproval?.gate;
+        const state = gate ? `awaiting ${gate}` : job.status;
+        const cost = lix ? formatLix(lix) : '—';
+        lines.push(`${(job.jobId ?? job.id).slice(0, 8)}  ${state.padEnd(16)} ${cost.padStart(11)}  ${job.kind ?? ''} ${job.title ?? ''}`.trimEnd());
+        if (job.openHoldLix)
+            lines.push(`          ${formatLix(job.openHoldLix)} still held`);
+        // A failed job that spent money and produced nothing is the thing worth seeing at a glance.
+        if (job.error && !job.publishedItemId)
+            lines.push(`          ${job.error}`);
+        if (job.recoverable && gate) {
+            lines.push(`          recoverable — helix assets status ${job.jobId ?? job.id} --pipeline dreamer`);
+        }
+    }
+    lines.push('', `${result.jobs.length} job(s)${result.total ? ` of ${result.total}` : ''} · ${formatLix((0, exports.roundLix)(spent))} spent across them`);
+    return lines.join('\n');
+}
+//# sourceMappingURL=money.js.map

package/dist/money.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"money.js","sourceRoot":"","sources":["../src/money.ts"],"names":[],"mappings":"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"}

package/dist/npc/capture.d.ts

@@ -0,0 +1,41 @@
+import type { NpcSample } from './metrics';
+import type { BrowserKey } from '../browser/launch';
+export type CaptureNpcOptions = {
+    directory: string;
+    /** Caption (and report) only this NPC id; the roster still lists everyone. */
+    npc?: string | undefined;
+    /** How many frames across the window (default 6). */
+    frames?: number | undefined;
+    /** The window the frames are spread over, in seconds (default 6). */
+    seconds?: number | undefined;
+    settleMs?: number | undefined;
+    timeoutMs?: number | undefined;
+    browser?: BrowserKey | undefined;
+    /** Where the PNGs land (default: a fresh temp dir). */
+    outDir?: string | undefined;
+    fallbackMounts?: Record<string, string> | undefined;
+    onProgress?: ((message: string) => void) | undefined;
+};
+export interface NpcFrame {
+    index: number;
+    /** Seconds after the first frame — the schedule the frame was taken on. */
+    atS: number;
+    file: string;
+    /** One line per NPC at that instant: where it is, what it is doing, what the world says about it. */
+    caption: string;
+    rows: NpcSample[];
+}
+export interface CaptureNpcResult {
+    directory: string;
+    outDir: string;
+    npc: string | null;
+    frames: NpcFrame[];
+    /** Every id seen across the strip, in first-seen order. */
+    roster: string[];
+    /** Always 'world-view' today — the inspect lane exposes no camera to aim at an NPC. */
+    cameraFocus: 'world-view';
+    notes: string[];
+}
+/** Exported for tests: the per-frame caption, which is the whole reason a frame is worth more than a still. */
+export declare function captionFor(rows: readonly NpcSample[], filter: string | null): string;
+export declare function captureNpc(opts: CaptureNpcOptions): Promise<CaptureNpcResult>;

package/dist/npc/capture.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captionFor = captionFor;
+exports.captureNpc = captureNpc;
+// `captureNpc` — the closing LOOK at an NPC, after inspectNpc's numbers are already right. Runs the
+// same headless lane, but writes a filmstrip: a canvas PNG at each frame time, each one captioned with
+// the npcSample row taken at that same moment, so "the guard is T-posing at 4 s" is answerable from the
+// pair rather than from a still with no clock on it.
+//
+// NO CAMERA CONTROL: the inspect lane's in-page protocol is ready/snapshot/npcIds/npcSample and nothing
+// else — inspect_world's focusNear is a NODE-side report lens, not a page camera. So these are plain
+// full-view frames of whatever the world's own camera is showing, and the result says so.
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const session_1 = require("./session");
+const DEFAULT_FRAMES = 6;
+const DEFAULT_SECONDS = 6;
+const MAX_FRAMES = 24;
+const fixed = (v) => v.toFixed(2);
+/** Exported for tests: the per-frame caption, which is the whole reason a frame is worth more than a still. */
+function captionFor(rows, filter) {
+    const shown = filter !== null ? rows.filter((r) => r.id === filter) : rows;
+    if (shown.length === 0)
+        return filter !== null ? `no sample for '${filter}' at this frame` : 'no NPCs in this frame';
+    return shown
+        .map((row) => {
+        const parts = [];
+        parts.push(row.position !== null ? `at (${fixed(row.position.x)}, ${fixed(row.position.y)}, ${fixed(row.position.z)})` : 'position unavailable');
+        if (row.locomotionState !== undefined)
+            parts.push(row.locomotionState);
+        if (row.arrived !== undefined)
+            parts.push(`arrived ${row.arrived}`);
+        if (row.hasPath)
+            parts.push(`path ${row.pathLength ?? '?'} waypoints`);
+        if (row.speed !== undefined)
+            parts.push(`${fixed(row.speed)} m/s`);
+        if (row.dead === true)
+            parts.push('DEAD');
+        if (row.ragdolled === true)
+            parts.push('ragdolled');
+        if (row.state !== undefined)
+            parts.push(`state ${JSON.stringify(row.state)}`);
+        return `${row.id} ${parts.join(', ')}`;
+    })
+        .join(' · ');
+}
+async function captureNpc(opts) {
+    const onProgress = opts.onProgress ?? (() => undefined);
+    const frameCount = Math.min(MAX_FRAMES, Math.max(1, Math.round(opts.frames ?? DEFAULT_FRAMES)));
+    const seconds = Math.max(0, opts.seconds ?? DEFAULT_SECONDS);
+    const settleMs = opts.settleMs ?? session_1.DEFAULT_SETTLE_MS;
+    const outDir = opts.outDir ?? (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'helix-npc-frames-'));
+    (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
+    const session = await (0, session_1.openNpcSession)({
+        directory: opts.directory,
+        timeoutMs: opts.timeoutMs ?? session_1.DEFAULT_TIMEOUT_MS,
+        browser: opts.browser,
+        fallbackMounts: opts.fallbackMounts,
+        onProgress,
+    });
+    try {
+        if (settleMs > 0)
+            await session.page.waitForTimeout(settleMs);
+        onProgress(`helper ready — ${frameCount} frame(s) over ${seconds}s after ${settleMs}ms settle`);
+        const spacingMs = frameCount > 1 ? (seconds * 1000) / (frameCount - 1) : 0;
+        const startedAt = Date.now();
+        const frames = [];
+        const roster = [];
+        for (let i = 0; i < frameCount; i++) {
+            const wait = startedAt + i * spacingMs - Date.now();
+            if (wait > 0)
+                await session.page.waitForTimeout(wait);
+            // Sample BEFORE the screenshot: the caption has to describe the moment the pixels were taken, and
+            // the screenshot is the slower of the two.
+            const rows = (await (0, session_1.readSample)(session.page));
+            for (const row of rows)
+                if (!roster.includes(row.id))
+                    roster.push(row.id);
+            const atMs = Math.round(i * spacingMs);
+            const file = (0, node_path_1.join)(outDir, `npc-frame-${String(i + 1).padStart(2, '0')}-t${String(atMs).padStart(5, '0')}ms.png`);
+            (0, node_fs_1.writeFileSync)(file, await session.page.locator('canvas').first().screenshot());
+            frames.push({ index: i, atS: Math.round(atMs) / 1000, file, caption: captionFor(rows, opts.npc ?? null), rows });
+            onProgress(`wrote ${file}`);
+        }
+        const notes = [
+            'Frames are the world\'s own full view — the inspect lane exposes no camera to aim at an NPC, so nothing here is ' +
+                'framed on one. Judge presence, body, pose and surroundings; take every distance from inspectNpc.',
+        ];
+        if (opts.npc !== undefined && !roster.includes(opts.npc)) {
+            notes.push(`no NPC with id '${opts.npc}' appeared in any frame${roster.length > 0 ? ` — the world reported: ${roster.join(', ')}.` : '.'}`);
+        }
+        return { directory: opts.directory, outDir, npc: opts.npc ?? null, frames, roster, cameraFocus: 'world-view', notes };
+    }
+    finally {
+        await session.close();
+    }
+}
+//# sourceMappingURL=capture.js.map

package/dist/npc/capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.js","sourceRoot":"","sources":["../../src/npc/capture.ts"],"names":[],"mappings":"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"}

package/dist/npc/format.d.ts

@@ -0,0 +1,2 @@
+import { type NpcInspection } from './metrics';
+export declare function formatNpcInspection(r: NpcInspection): string;

package/dist/npc/format.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatNpcInspection = formatNpcInspection;
+// Plain-English rendering of an NPC inspection — same job as gesture/inspect's formatInspect: an agent
+// with no eyes has to be able to tell a working NPC from a broken one from this text alone. Pure over
+// the metrics payload (no transport, no fs), so it is unit-testable beside the math it renders.
+const metrics_1 = require("./metrics");
+const m = (v) => `${v.toFixed(2)} m`;
+const s = (v) => `t=${v.toFixed(2)}s`;
+const pct = (v) => `${Math.round(v * 100)}%`;
+const vec = (v) => `(${v.x.toFixed(2)}, ${v.y.toFixed(2)}, ${v.z.toFixed(2)})`;
+const renderTimeline = (transitions) => transitions.map((t) => `${t.to} at ${s(t.atS)}`).join(' → ');
+/** One "what to check next" line per distinct problem, in the order a reader should act on them. */
+function advice(r) {
+    const out = [];
+    const any = (test) => r.npcs.some(test);
+    if (any((n) => n.flags.includes('never-moved'))) {
+        out.push("an NPC that never moved is usually on the default body: 'stand' tier, where movement intent is inert by " +
+            "design — give it body: 'physics' (which needs staticsFrom on the NpcScene) or move it with teleport().");
+    }
+    if (any((n) => n.flags.includes('no-position-reads'))) {
+        out.push('no position was ever read off a driver — check that the pool\'s get(id) returns a handle exposing driver.position.');
+    }
+    if (any((n) => n.flags.includes('dead-throughout'))) {
+        out.push('an NPC was dead for the whole run, so nothing it did is representative — revive or respawn it before measuring behaviour.');
+    }
+    if (any((n) => n.stuckWindows.length > 0)) {
+        out.push(`stuck windows use the driver's OWN rule (under ${metrics_1.STUCK_MIN_PROGRESS_M} m of ground made in ${metrics_1.STUCK_WINDOW_S} s). The two ` +
+            'silent causes: re-seeking every frame (seek() resets the stuck window, which disables the sideways commit that ' +
+            'rounds a wall — re-seek only once the target has actually moved), and a doorway the nav grid rasterized shut ' +
+            '(every blocker is inflated by agentRadiusM + half a cell, so gaps under ~1.3 m close at defaults).');
+    }
+    if (any((n) => n.flags.includes('moving-without-a-path'))) {
+        out.push('an NPC moved without ever holding a planned path: the NavGrid produced no route and the seek degraded to direct ' +
+            'steering, which is SILENT by design — check the page console for its skipped-geometry warning (v1 rasterizes ' +
+            'yaw-aligned cuboids only), or accept direct steering deliberately.');
+    }
+    if (any(closedRegression)) {
+        out.push('an NPC moved but never closed distance on the target — the classic cause is a behaviour that seeks first and reads ' +
+            'arrived after, which reads false every frame; read arrived BEFORE re-seeking, in the same behaviour.');
+    }
+    return out;
+}
+/** Moved meaningfully yet ended no closer to the target — a chase that is not chasing. */
+const closedRegression = (npc) => npc.target !== null && npc.pathTracedM >= metrics_1.MOVED_EPSILON_M && npc.target.closedM <= 0.05;
+function formatNpcInspection(r) {
+    const out = [
+        `npc inspect — ${r.npcs.length} NPC(s), ${r.seconds.toFixed(1)}s at ${r.sampleHz} Hz ` +
+            `(${r.sampleCount} samples, ${r.settleMs}ms settle)`,
+    ];
+    if (r.npcFilter !== null)
+        out.push(`filtered to '${r.npcFilter}' — the world reported: ${r.roster.join(', ') || '(none)'}`);
+    if (r.target !== null)
+        out.push(`target: ${vec(r.target)}`);
+    for (const note of r.notes)
+        out.push(`! ${note}`);
+    for (const npc of r.npcs) {
+        out.push(`\n${npc.id} — ${npc.samples} samples over ${npc.spanS.toFixed(1)}s`);
+        if (npc.position.first !== null && npc.position.last !== null) {
+            out.push(`  from ${vec(npc.position.first)} to ${vec(npc.position.last)}`);
+        }
+        out.push(`  travelled ${m(npc.pathTracedM)}, ended ${m(npc.netDisplacementM)} from where it started` +
+            (npc.progressRatio !== null ? ` (progress ratio ${npc.progressRatio.toFixed(2)} — 1.00 is a straight line)` : ''));
+        out.push(`  average ${npc.averageSpeedMps.toFixed(2)} m/s over the run` +
+            (npc.topReportedSpeedMps !== null ? ` · top reported speed ${npc.topReportedSpeedMps.toFixed(2)} m/s` : ''));
+        if (npc.target !== null) {
+            const t = npc.target;
+            out.push(`  target: ${m(t.startM)} away at the start → ${m(t.finalM)} at the end (${t.closedM >= 0 ? 'closed' : 'LOST'} ` +
+                `${m(Math.abs(t.closedM))}); closest ${m(t.closestM)} at ${s(t.closestAtS)}`);
+        }
+        out.push(npc.arrivedInitial === null
+            ? '  arrived: the driver never reported it'
+            : `  arrived: started ${npc.arrivedInitial}` +
+                (npc.arrivedEdges.length === 0
+                    ? ' and never changed'
+                    : ` → ${npc.arrivedEdges.map((e) => `${e.arrived} at ${s(e.atS)}`).join(' → ')}`));
+        out.push(`  nav path: ${pct(npc.hasPathRatio)} of samples were following a planned route` +
+            (npc.maxPathLength !== null ? ` (longest plan ${npc.maxPathLength} waypoints)` : ''));
+        out.push(npc.stuckWindows.length === 0
+            ? '  stuck: none'
+            : `  stuck: ${npc.stuckWindows.length} window(s), ${npc.stuckSeconds.toFixed(2)}s total — ` +
+                npc.stuckWindows.map((w) => `${s(w.fromS)}..${s(w.toS)} (${m(w.progressM)} made)`).join(', '));
+        if (npc.locomotionTimeline.length > 0)
+            out.push(`  locomotion: ${renderTimeline(npc.locomotionTimeline)}`);
+        if (npc.stateTimeline.length > 0)
+            out.push(`  world state: ${renderTimeline(npc.stateTimeline)}`);
+        if (npc.ragdolledAnySample)
+            out.push('  ragdolled during the run');
+        for (const flag of npc.flags)
+            out.push(`  ⚠ ${flag}`);
+        if (closedRegression(npc))
+            out.push('  ⚠ moved but ended no closer to the target');
+    }
+    const next = advice(r);
+    if (next.length > 0) {
+        out.push('\nwhat to check next:');
+        for (const line of next)
+            out.push(`  - ${line}`);
+    }
+    return out.join('\n');
+}
+//# sourceMappingURL=format.js.map

package/dist/npc/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/npc/format.ts"],"names":[],"mappings":"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"}

package/dist/npc/inspect.d.ts

@@ -0,0 +1,23 @@
+import type { NpcInspection, Vec3 } from './metrics';
+import type { BrowserKey } from '../browser/launch';
+export { formatNpcInspection } from './format';
+export type { NpcInspection, NpcMetrics, NpcSample, StuckWindow, Transition, TargetProgress } from './metrics';
+export type InspectNpcOptions = {
+    directory: string;
+    /** How long to watch, in seconds (default 8). */
+    seconds?: number | undefined;
+    /** Samples per second (default 10, capped at 60). */
+    sampleHz?: number | undefined;
+    /** Report only this NPC id; every id seen still lands in the roster. */
+    npc?: string | undefined;
+    /** A world-space point to measure progress against — the destination the behaviour is meant to reach. */
+    target?: Vec3 | undefined;
+    /** Frames/assets settle time between helper-ready and the first sample. */
+    settleMs?: number | undefined;
+    timeoutMs?: number | undefined;
+    /** Diagnostic override: launch only this candidate, no fallback. */
+    browser?: BrowserKey | undefined;
+    fallbackMounts?: Record<string, string> | undefined;
+    onProgress?: ((message: string) => void) | undefined;
+};
+export declare function inspectNpc(opts: InspectNpcOptions): Promise<NpcInspection>;