@jeffreyjyz/reqshape 0.0.0-stage → 0.1.0

package/src/constants/keywords.ts

@@ -0,0 +1,91 @@
+/**
+ * Prompts that ask for nothing worth modelling: acknowledgements, greetings,
+ * and the one-word nudges an agentic loop hands back. Matched after punctuation
+ * is stripped, so `Hi!` and `thanks.` land here too.
+ */
+export const DEFAULT_KEYWORDS = [
+	"hi",
+	"hi there",
+	"hey",
+	"hello",
+	"hello there",
+	"yo",
+	"sup",
+	"hiya",
+	"howdy",
+	"thanks",
+	"thank you",
+	"ty",
+	"thx",
+	"cheers",
+	"nice",
+	"great",
+	"awesome",
+	"perfect",
+	"cool",
+	"sweet",
+	"lovely",
+	"well done",
+	"good job",
+	"nice work",
+	"ok",
+	"okay",
+	"k",
+	"sure",
+	"yes",
+	"yeah",
+	"yep",
+	"y",
+	"no",
+	"nope",
+	"nah",
+	"n",
+	"continue",
+	"go",
+	"go on",
+	"go ahead",
+	"proceed",
+	"next",
+	"carry on",
+	"keep going",
+	"resume",
+	"done",
+	"stop",
+	"wait",
+	"hold on",
+	"hmm",
+	"hm",
+	"oh",
+	"ah",
+	"i see",
+	"got it",
+	"makes sense",
+	"make sense",
+	"sounds good",
+	"looks good",
+	"lgtm",
+	"agreed",
+	"right",
+	"correct",
+	"exactly",
+	"indeed",
+];
+
+/**
+ * Filler that rides along with an acknowledgement — `hey there`, `continue
+ * please`, `thanks bro`. Only the all-words rule consults it, and it still
+ * needs a real keyword in the prompt, so a filler-heavy *ask* survives.
+ */
+export const FILLER = new Set([
+	"there",
+	"then",
+	"again",
+	"please",
+	"pls",
+	"bro",
+	"man",
+	"dude",
+	"guys",
+	"all",
+	"everyone",
+]);

package/src/constants/layout.ts

@@ -0,0 +1,6 @@
+/** Column widths and the section-label gutter, shared by the text renderers. */
+export const LABEL = 10;
+export const NAME = 26;
+export const PLAN = 11;
+export const MONEY = 12;
+export const CELL = 10;

package/src/constants/providers.ts

@@ -0,0 +1,2 @@
+/** Provider ids that mean CommandCode: the CLI, and the plugin's API variants. */
+export const CC_PREFIXES = ["command-code", "commandcode"];

package/src/index.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env bun
+import { run } from "./cli/run.ts";
+
+try {
+	process.exitCode = await run(process.argv.slice(2));
+} catch (error) {
+	console.error(
+		`reqshape: ${error instanceof Error ? error.message : String(error)}`,
+	);
+	process.exitCode = 1;
+}

package/src/market/entries.ts

@@ -0,0 +1,89 @@
+import type { MpcJson, MpcSide, ProviderId, RateEntry } from "./rates.ts";
+import { numberOr } from "./sources.ts";
+
+/**
+ * The plan's window caps as a share of its monthly allowance. Taken from the
+ * plan block when published, otherwise read back off a priced row — mpc has
+ * already applied the provider's own rule there (20%/50% on OpenCode Go, 20%/50%
+ * on GOAT and Pro, 30%/60% on Max and Go), so stating the rule again here is how
+ * the two would drift apart.
+ */
+function ratiosOf(
+	json: MpcJson,
+): Map<string, { fiveHour: number; weekly: number }> {
+	const ratios = new Map<string, { fiveHour: number; weekly: number }>();
+	for (const [id, plan] of Object.entries(json.plans ?? {})) {
+		const credits = numberOr(plan.credits);
+		const fiveHour = numberOr(plan.fiveHour);
+		const weekly = numberOr(plan.weekly);
+		if (credits && credits > 0 && fiveHour !== null && weekly !== null) {
+			ratios.set(id, {
+				fiveHour: fiveHour / credits,
+				weekly: weekly / credits,
+			});
+		}
+	}
+	for (const row of json.rows ?? []) {
+		for (const side of [row.oc, row.cc]) {
+			if (!side?.provider || ratios.has(side.provider)) continue;
+			const month = numberOr(side.requestsPerMonth);
+			const fiveHour = numberOr(side.requestsPerFiveHour);
+			const weekly = numberOr(side.requestsPerWeek);
+			if (!month || month <= 0 || fiveHour === null || weekly === null) {
+				continue;
+			}
+			ratios.set(side.provider, {
+				fiveHour: fiveHour / month,
+				weekly: weekly / month,
+			});
+		}
+	}
+	return ratios;
+}
+
+function entryOf(
+	key: string,
+	model: string,
+	provider: ProviderId,
+	side: MpcSide,
+	ratios: Map<string, { fiveHour: number; weekly: number }>,
+): RateEntry | null {
+	const pricing = side.pricing;
+	const allowance = numberOr(side.allowance);
+	// A model with no pricing is not a zero-cost model; it is unpriced.
+	if (!pricing || allowance === null) return null;
+	const ratio = ratios.get(provider);
+	return {
+		key,
+		model,
+		provider,
+		plan: side.plan ?? "",
+		input: numberOr(pricing.input) ?? 0,
+		output: numberOr(pricing.output) ?? 0,
+		cacheRead: numberOr(pricing.cacheRead),
+		cacheWrite: numberOr(pricing.cacheWrite),
+		allowance,
+		ratio5h: ratio?.fiveHour ?? null,
+		ratioWeek: ratio?.weekly ?? null,
+		free: Boolean(side.free),
+	};
+}
+
+/** Every model the two plans sell, as (model, provider) entries. */
+export function entriesOf(json: MpcJson): RateEntry[] {
+	const ratios = ratiosOf(json);
+	const entries: RateEntry[] = [];
+	for (const row of json.rows ?? []) {
+		const key = row.key ?? "";
+		const model = row.name ?? key;
+		for (const [provider, side] of [
+			["oc-go", row.oc],
+			["cc", row.cc],
+		] as const) {
+			if (!side) continue;
+			const entry = entryOf(key, model, provider, side, ratios);
+			if (entry) entries.push(entry);
+		}
+	}
+	return entries;
+}

package/src/market/project.ts

@@ -0,0 +1,61 @@
+import type { Profile } from "~/types.ts";
+import type { RateEntry } from "./rates.ts";
+
+/** One model's answer to "how many requests does my allowance buy me?". */
+export interface Projection {
+	entry: RateEntry;
+	costPerReq: number;
+	requestsPerMonth: number;
+	requestsPerFiveHour: number | null;
+	requestsPerWeek: number | null;
+	/** Cache reads priced at the input rate because no cache rate is published. */
+	cacheAtInput: boolean;
+	/** Same, for cache writes. */
+	writeAtInput: boolean;
+}
+
+/**
+ * Price one request of the measured shape on one model.
+ *
+ * Reasoning tokens bill as output on every provider, so they join the output
+ * term. A rate the model does not publish (cache write is null on most of the
+ * catalogue) falls back to the input rate rather than to zero: not knowing a
+ * price is no reason to assume it is free.
+ */
+export function project(entry: RateEntry, profile: Profile): Projection {
+	const output = profile.output + profile.reasoning;
+	const cacheRate = entry.cacheRead ?? entry.input;
+	const writeRate = entry.cacheWrite ?? entry.input;
+	const costPerReq =
+		(profile.input * entry.input +
+			output * entry.output +
+			profile.cacheRead * cacheRate +
+			profile.cacheWrite * writeRate) /
+		1e6;
+
+	const requestsPerMonth =
+		costPerReq > 0
+			? entry.allowance / costPerReq
+			: Number.POSITIVE_INFINITY;
+
+	return {
+		entry,
+		costPerReq,
+		requestsPerMonth,
+		requestsPerFiveHour:
+			entry.ratio5h === null ? null : requestsPerMonth * entry.ratio5h,
+		requestsPerWeek:
+			entry.ratioWeek === null
+				? null
+				: requestsPerMonth * entry.ratioWeek,
+		cacheAtInput: entry.cacheRead === null && profile.cacheRead > 0,
+		writeAtInput: entry.cacheWrite === null && profile.cacheWrite > 0,
+	};
+}
+
+export function projectAll(
+	entries: RateEntry[],
+	profile: Profile,
+): Projection[] {
+	return entries.map((entry) => project(entry, profile));
+}

package/src/market/rates.ts

@@ -0,0 +1,103 @@
+export type ProviderId = "oc-go" | "cc" | "custom";
+
+export interface RateEntry {
+	key: string;
+	model: string;
+	provider: ProviderId;
+	/** Plan label as the provider writes it: Go, GOAT, Pro, Max 20x — or `custom`. */
+	plan: string;
+	input: number;
+	output: number;
+	/** Null when the model publishes no cache-read rate; bill it as input. */
+	cacheRead: number | null;
+	cacheWrite: number | null;
+	/** Dollars of list-rate spend the plan grants this model per month. */
+	allowance: number;
+	/** Share of the allowance the plan opens per five hours, and per week. */
+	ratio5h: number | null;
+	ratioWeek: number | null;
+	free: boolean;
+}
+
+export interface MpcSide {
+	provider?: string;
+	plan?: string;
+	pricing?: {
+		input?: number;
+		output?: number;
+		cacheRead?: number | null;
+		cacheWrite?: number | null;
+	} | null;
+	allowance?: number | null;
+	requestsPerMonth?: number;
+	requestsPerFiveHour?: number;
+	requestsPerWeek?: number;
+	free?: boolean;
+}
+
+export interface MpcJson {
+	plans?: Record<
+		string,
+		{
+			label?: string;
+			credits?: number;
+			fiveHour?: number | null;
+			weekly?: number | null;
+		}
+	>;
+	rows?: Array<{
+		key?: string;
+		name?: string;
+		oc?: MpcSide | null;
+		cc?: MpcSide | null;
+	}>;
+}
+
+export interface CustomRates {
+	label: string;
+	input: number;
+	output: number;
+	cacheRead: number | null;
+	cacheWrite: number | null;
+	budget: number;
+	cap5h: number | null;
+	capWeek: number | null;
+}
+
+/** Full provider name, for the JSON payload's consumers. */
+export function providerName(provider: ProviderId): string {
+	if (provider === "oc-go") return "OpenCode";
+	return provider === "cc" ? "CommandCode" : "custom";
+}
+
+/** Column-width provider tag. */
+export function shortProvider(provider: ProviderId): string {
+	if (provider === "oc-go") return "OC";
+	return provider === "cc" ? "CC" : "custom";
+}
+
+/** e.g. "OC Go", "CC GOAT". */
+export function planLabel(entry: RateEntry): string {
+	return entry.provider === "custom"
+		? "custom"
+		: `${shortProvider(entry.provider)} ${entry.plan}`.trim();
+}
+
+export function customEntry(custom: CustomRates): RateEntry {
+	const share = (cap: number | null): number | null =>
+		cap !== null && custom.budget > 0 ? cap / custom.budget : null;
+	return {
+		key: "custom",
+		model: custom.label,
+		provider: "custom",
+		plan: "custom",
+		input: custom.input,
+		output: custom.output,
+		cacheRead: custom.cacheRead,
+		cacheWrite: custom.cacheWrite,
+		allowance: custom.budget,
+		ratio5h: share(custom.cap5h),
+		ratioWeek: share(custom.capWeek),
+		free: false,
+	};
+}

package/src/market/sources.ts

@@ -0,0 +1,62 @@
+import { spawnSync } from "node:child_process";
+import type { MpcJson } from "./rates.ts";
+
+export interface AccountSummary {
+	plan: string;
+	requests: number;
+	periodEnd: string;
+}
+
+export function numberOr(value: unknown): number | null {
+	return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+/** Run a sibling CLI and parse its JSON, with the failure mode worth reading. */
+function runJson<T>(bin: string, args: string[]): T {
+	const result = spawnSync(bin, args, {
+		encoding: "utf8",
+		maxBuffer: 64 * 1024 * 1024,
+	});
+	const detail =
+		(result.stderr || "").trim() ||
+		result.error?.message ||
+		"no output (is it installed and on PATH?)";
+	if (result.error || result.status !== 0 || !result.stdout) {
+		throw new Error(
+			`${bin} ${args.join(" ")} failed: ${detail.slice(0, 240)}`,
+		);
+	}
+	return JSON.parse(result.stdout) as T;
+}
+
+/** mpc knows both plans' pricing, allowances and window rules. */
+export function loadMpc(bin: string): MpcJson {
+	// `--shape off`: reqshape only needs mpc's pricing and allowances, and it
+	// has no workload of its own to price here. mpc's default `--shape auto`
+	// shells out to reqshape, so without the flag this call would recurse
+	// (mpc -> reqshape -> mpc -> ...).
+	return runJson<MpcJson>(bin, ["--json", "--shape", "off"]);
+}
+
+/**
+ * The account's own count of requests this period. Optional context, never
+ * fatal: an unauthenticated or offline cmduse just means no line is printed.
+ */
+export function loadAccount(bin: string): AccountSummary | null {
+	try {
+		const json = runJson<{
+			plan?: string;
+			periodEnd?: string;
+			summary?: { requests?: number };
+		}>(bin, ["-1", "--json"]);
+		const requests = numberOr(json.summary?.requests);
+		if (requests === null) return null;
+		return {
+			plan: json.plan ?? "",
+			requests,
+			periodEnd: json.periodEnd ?? "",
+		};
+	} catch {
+		return null;
+	}
+}

package/src/measure/asks.ts

@@ -0,0 +1,83 @@
+import { BOUNDARY } from "~/constants/asks.ts";
+import type { Ask, AskKind, Req } from "~/types.ts";
+import type { RawMessage } from "./rows.ts";
+import type { SessionRow } from "./store.ts";
+
+function numberOr(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+function toReq(message: RawMessage, position: number): Req {
+	const tokens = message.tokens;
+	return {
+		model: message.model,
+		provider: message.provider,
+		tokensIn: numberOr(tokens?.input),
+		output: numberOr(tokens?.output),
+		reasoning: numberOr(tokens?.reasoning),
+		cacheRead: numberOr(tokens?.cache?.read),
+		cacheWrite: numberOr(tokens?.cache?.write),
+		cost: numberOr(message.cost),
+		position,
+	};
+}
+
+/**
+ * Group a session's rows into asks. Messages arrive grouped by session and
+ * ordered by the store's own sequence, so an ask is simply the run of assistant
+ * rows between one boundary and the next. Position counts across the whole
+ * session rather than the ask, because that is the axis a re-read context grows
+ * along: the first request of a conversation is cheap, the hundredth is not.
+ */
+export function buildAsks(
+	messages: RawMessage[],
+	sessions: Map<string, SessionRow>,
+): Ask[] {
+	const asks: Ask[] = [];
+	let current: Ask | null = null;
+	let sessionID = "";
+	let position = 0;
+
+	const flush = () => {
+		if (current) asks.push(current);
+		current = null;
+	};
+	const open = (message: RawMessage, kind: AskKind): Ask => {
+		const session = sessions.get(message.sessionID);
+		return {
+			sessionID: message.sessionID,
+			directory: session?.directory ?? "",
+			child: session?.child ?? false,
+			kind,
+			text: message.text,
+			time: message.time,
+			reqs: [],
+		};
+	};
+
+	for (const message of messages) {
+		if (message.sessionID !== sessionID) {
+			flush();
+			sessionID = message.sessionID;
+			position = 0;
+		}
+		const boundary = BOUNDARY[message.kind];
+		if (boundary) {
+			flush();
+			current = open(message, boundary);
+			continue;
+		}
+		// Everything that is not a boundary continues the ask: bookkeeping rows
+		// (idle, agent-switched, model-switched) and the interjections above.
+		if (message.kind !== "assistant") continue;
+		// A turn without tokens is still streaming; it has not been billed yet.
+		if (!message.tokens) continue;
+		position += 1;
+		// Reqs before any boundary belong to nobody; keep them visible rather
+		// than silently dropping them.
+		current ??= open(message, "orphan");
+		current.reqs.push(toReq(message, position));
+	}
+	flush();
+	return asks;
+}

package/src/measure/filter.ts

@@ -0,0 +1,116 @@
+import { FILLER } from "~/constants/keywords.ts";
+import type { Ask, DropCount } from "~/types.ts";
+
+export interface FilterOptions {
+	/** `user` keeps only the prompts you typed, dropping subagent sessions. */
+	sessions: "user" | "all";
+	keywords: Set<string>;
+	minChars: number;
+	minOutput: number;
+	keepTrivial: boolean;
+	/** Epoch ms floor; 0 keeps everything. */
+	since: number;
+	/** Substring matched against the session's directory; "" keeps everything. */
+	project: string;
+}
+
+export interface FilterResult {
+	kept: Ask[];
+	drops: DropCount[];
+}
+
+/** Lowercase, punctuation-free, single-spaced — so `Hi!` and `hi` are the same prompt. */
+export function normalizePrompt(text: string): string {
+	return text
+		.toLowerCase()
+		.replace(/[^\p{L}\p{N}\s]+/gu, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+/**
+ * Why this prompt is noise, or null when it is worth profiling. A prompt made
+ * only of emoji normalises away to nothing, which is its own answer.
+ */
+export function trivialReason(
+	text: string,
+	keywords: Set<string>,
+	minChars: number,
+): string | null {
+	const normalized = normalizePrompt(text);
+	if (!normalized) return "empty prompt";
+	if (keywords.has(normalized)) return "trivial prompt";
+	const words = normalized.split(" ");
+	if (
+		words.length > 1 &&
+		words.some((word) => keywords.has(word)) &&
+		words.every((word) => keywords.has(word) || FILLER.has(word))
+	) {
+		return "trivial prompt";
+	}
+	if (minChars > 0 && normalized.length < minChars) return "short prompt";
+	return null;
+}
+
+function outputOf(ask: Ask): number {
+	let total = 0;
+	for (const req of ask.reqs) total += req.output;
+	return total;
+}
+
+function dropOf(ask: Ask, reason: string, seen: Map<string, DropCount>): void {
+	const entry = seen.get(reason) ?? { reason, asks: 0, reqs: 0 };
+	entry.asks += 1;
+	entry.reqs += ask.reqs.length;
+	seen.set(reason, entry);
+}
+
+/**
+ * Decide which asks describe real work. Every rejection is counted, so the
+ * numbers stay auditable rather than quietly cleaned.
+ */
+export function filterAsks(asks: Ask[], options: FilterOptions): FilterResult {
+	const kept: Ask[] = [];
+	const drops = new Map<string, DropCount>();
+
+	for (const ask of asks) {
+		if (options.since > 0 && ask.time > 0 && ask.time < options.since) {
+			dropOf(ask, "before --since", drops);
+			continue;
+		}
+		if (options.project && !ask.directory.includes(options.project)) {
+			dropOf(ask, "other project", drops);
+			continue;
+		}
+		if (options.sessions === "user" && ask.child) {
+			dropOf(ask, "subagent session", drops);
+			continue;
+		}
+		if (ask.kind !== "user") {
+			dropOf(ask, `${ask.kind} prompt`, drops);
+			continue;
+		}
+		if (ask.reqs.length === 0) {
+			dropOf(ask, "no model call", drops);
+			continue;
+		}
+		if (!options.keepTrivial) {
+			const reason = trivialReason(
+				ask.text,
+				options.keywords,
+				options.minChars,
+			);
+			if (reason) {
+				dropOf(ask, reason, drops);
+				continue;
+			}
+			if (options.minOutput > 0 && outputOf(ask) < options.minOutput) {
+				dropOf(ask, "under --min-output", drops);
+				continue;
+			}
+		}
+		kept.push(ask);
+	}
+
+	return { kept, drops: [...drops.values()].sort((a, b) => b.reqs - a.reqs) };
+}