@iowarp/clio-coder 0.5.0 → 0.5.2

package/src/domains/observability/background-memory-usage.ts

@@ -10,7 +10,7 @@
  *
  * The two writes are the same pair the side-question path makes: the
  * in-process cost tracker under the `background-memory` label, which is what
- * `/cost` folds, and one durable row in the out-of-turn usage store, which is
+ * `/usage` folds, and one durable row in the out-of-turn usage store, which is
  * what an archive reader folds after the process is gone.
  */
 

package/src/domains/observability/cost.ts

@@ -7,7 +7,7 @@
  *
  * Per-entry token breakdown (input/output/cacheRead/cacheWrite/reasoning)
  * matches the shape of pi-ai's `Usage` plus provider-specific reasoning detail
- * fields. The /cost overlay aggregates it via `aggregateCostEntries`; the TUI
+ * fields. The /usage overlay aggregates it via `aggregateCostEntries`; the TUI
  * footer consumes the session sum through `ObservabilityContract.sessionTokens()`.
  */
 
@@ -92,7 +92,7 @@ export function formatCostAggregate(cost: CostAggregate | null | undefined): str
 
 /**
  * What a fixed-width surface says when there is no cost claim. The footer and
- * `/cost` drop their cost field instead; a table cell that owns a column cannot,
+ * `/usage` drop their cost field instead; a table cell that owns a column cannot,
  * so it says the same thing in words rather than inventing `$0.00`.
  */
 export const COST_NOT_MEASURED = "not measured";
@@ -134,7 +134,7 @@ export interface UsageBreakdown {
 }
 
 /**
- * What produced a priced call, when it was not an ordinary turn. `/cost` and
+ * What produced a priced call, when it was not an ordinary turn. `/usage` and
  * the usage surfaces separate these out so an operator can see that money was
  * spent beside the session rather than inside it.
  */

package/src/domains/observability/extension.ts

@@ -53,7 +53,7 @@ function recordDispatchCost(
 	}
 	telemetry.record("counter", "tokens.total", payload.tokenCount);
 	// Dispatch terminal payloads carry the same full split as receipts. Preserve
-	// it so /cost and the footer agree with the fleet board instead of showing
+	// it so /usage and the footer agree with the fleet board instead of showing
 	// zero input/output/cache for worker-only sessions.
 	cost.accumulate(
 		payload.targetId,

package/src/domains/observability/metrics.ts

@@ -1,5 +1,5 @@
 /**
- * Thin reducer over TelemetrySnapshot. Produces a view the TUI + /cost overlay
+ * Thin reducer over TelemetrySnapshot. Produces a view the TUI + /usage overlay
  * consume. Stays pure so tests can hand-roll snapshots and assert the shape.
  */
 

package/src/domains/prompts/compiler.ts

@@ -256,7 +256,7 @@ function sessionHasContext(inputs: SessionPromptInputs): boolean {
 	return toolSurfaceHasTool(inputs.toolNames, "context") && turnAllowsTool(inputs.turnConstraints, "context");
 }
 
-function sessionCanUseSkills(inputs: SessionPromptInputs): boolean {
+export function sessionCanUseSkills(inputs: SessionPromptInputs): boolean {
 	return (
 		sessionHasContext(inputs) &&
 		inputs.skillDiscoveryEnabled !== false &&

package/src/domains/prompts/extension.ts

@@ -18,7 +18,14 @@ import {
 	selectActiveRules,
 } from "../context/index.js";
 import { detectRunIdentity } from "../dispatch/run-identity.js";
-import { compile, compileWorker, type RenderedPromptFragment } from "./compiler.js";
+import { isAutonomyLevel, modelMayActivateSkills } from "../safety/autonomy.js";
+import {
+	compile,
+	compileWorker,
+	type RenderedPromptFragment,
+	type SessionPromptInputs,
+	sessionCanUseSkills,
+} from "./compiler.js";
 import type { CompileSessionPromptInput, CompileWorkerPromptInput, PromptsContract } from "./contract.js";
 import { type FragmentTable, loadFragments } from "./fragment-loader.js";
 import { sha256 } from "./hash.js";
@@ -182,6 +189,7 @@ export function createPromptsBundle(
 				additionalFragments: [
 					...sources.workspaceRoot,
 					...sources.clioRepoAwareness,
+					...selfDevelopmentSkillFragments(sources.clioRepoAwareness.length > 0, sessionInputs, safety),
 					...renderCustomizationFragments(sources.customization, cwd, input.workingContextPaths ?? []).fragments,
 				],
 			});
@@ -372,6 +380,7 @@ function clioRepoAwarenessFragments(cwd: string): RenderedPromptFragment[] {
 	const body = [
 		"# Clio Source Tree",
 		"This workspace is Clio Coder's own source tree.",
+		`Source repository root: ${JSON.stringify(awareness.repoRoot)}.`,
 		"When running inside this repo, Clio can modify her own TUI, skills, agents, tools, prompts, context/bootstrap, and harness as ordinary local source work when the user asks.",
 		"Shared contribution/publishing/push/PR/release requires explicit user intent and normal Git/GitHub etiquette. Do not imply autonomous publishing.",
 	].join("\n");
@@ -385,3 +394,31 @@ function clioRepoAwarenessFragments(cwd: string): RenderedPromptFragment[] {
 		},
 	];
 }
+
+/** A small task-aware nudge; actual loading still uses normal skill admission. */
+function selfDevelopmentSkillFragments(
+	selfRepo: boolean,
+	inputs: SessionPromptInputs,
+	autonomy: string,
+): RenderedPromptFragment[] {
+	if (!selfRepo || !sessionCanUseSkills(inputs) || inputs.turnConstraints?.mode === "proposal") return [];
+	const activation = isAutonomyLevel(autonomy) && modelMayActivateSkills(autonomy);
+	const body = [
+		"# Self-development skills",
+		"For a task that changes Clio's source, harness, prompts, or library, use clio-coder-dev before editing and clio-coder-test when choosing validation. Skip this workflow for unrelated or self-contained questions.",
+		'These two skills are discoverable from this checkout\'s library/skills/meta when no installed package owns their names. Check context(scope="skills") for current readiness; disabled, damaged, or hidden skills stay unavailable.',
+		activation
+			? 'Load each relevant ready skill with context(scope="skills", name="clio-coder-dev") or context(scope="skills", name="clio-coder-test") as needed, without waiting for a separate skill request. Reuse already loaded guidance; do not load every reference or the whole catalog.'
+			: "Only the operator activates skills at this autonomy level. Suggest /skill clio-coder-dev or /skill clio-coder-test when relevant, then continue permitted work without waiting or bypassing the activation gate.",
+		"Read CONTRIBUTING.md and the assigned sprint packet from the detected repository root. A plan or skill does not launch an unapproved implementation sprint or authorize publication.",
+	].join("\n");
+	return [
+		{
+			id: "context.self-development-skills",
+			relPath: "inline/self-development-skills",
+			body,
+			contentHash: sha256(body),
+			dynamic: true,
+		},
+	];
+}

package/src/domains/quota/anthropic-max-provider.ts

@@ -0,0 +1,134 @@
+/**
+ * Quota adapter for the `anthropic-max` runtime, the account Clio itself
+ * spends when it runs a native turn.
+ *
+ * Unlike `claude-code`, this credential belongs to Clio: it is the OAuth
+ * record her own auth storage persists under the `anthropic` provider id.
+ * The adapter reads the stored credential without triggering a refresh,
+ * because a quota read must never mutate an authentication record.
+ *
+ * Both adapters can point at the same Anthropic account. That is a display
+ * concern rather than a correctness one: each reports what its own
+ * credential sees, and a consumer that shows both should say which
+ * credential produced which row.
+ */
+
+import { openAuthStorage } from "../providers/auth/index.js";
+import { fetchAnthropicUsage } from "./anthropic-usage.js";
+import type { QuotaProvider, UsageSnapshot } from "./types.js";
+
+export const ANTHROPIC_MAX_QUOTA_PROVIDER_ID = "anthropic-max";
+
+/** The provider id Clio's auth storage files an Anthropic OAuth credential under. */
+const AUTH_PROVIDER_ID = "anthropic";
+const DISPLAY_NAME = "Anthropic Max";
+const REQUEST_TIMEOUT_MS = 15_000;
+
+/** The subset of Clio's stored OAuth credential this adapter needs. */
+export interface AnthropicMaxCredentials {
+	accessToken: string;
+	/** Epoch milliseconds the access token expires, or null when the record omits it. */
+	expiresAtMs: number | null;
+	hasRefreshToken: boolean;
+}
+
+export interface AnthropicMaxQuotaOptions {
+	readCredentials?: () => Promise<AnthropicMaxCredentials | null>;
+	fetch?: typeof globalThis.fetch;
+	timeoutMs?: number;
+	now?: () => Date;
+}
+
+/** Shape a stored auth credential into the fields a usage read needs. */
+export function parseStoredAnthropicCredential(raw: unknown): AnthropicMaxCredentials | null {
+	if (!isRecord(raw) || raw.type !== "oauth") return null;
+	const access = raw.access;
+	if (typeof access !== "string" || access.length === 0) return null;
+	const refresh = raw.refresh;
+	return {
+		accessToken: access,
+		expiresAtMs: asNumber(raw.expires),
+		hasRefreshToken: typeof refresh === "string" && refresh.length > 0,
+	};
+}
+
+/**
+ * Read Clio's stored Anthropic credential.
+ *
+ * `AuthStorage.get` is the accessor that does no refresh, unlike
+ * `resolveApiKey`, which renews an expiring credential as a side effect.
+ */
+async function readStoredCredential(): Promise<AnthropicMaxCredentials | null> {
+	try {
+		return parseStoredAnthropicCredential(openAuthStorage().get(AUTH_PROVIDER_ID));
+	} catch {
+		return null;
+	}
+}
+
+/** Build the read-only `anthropic-max` quota adapter. */
+export function createAnthropicMaxQuotaProvider(options: AnthropicMaxQuotaOptions = {}): QuotaProvider {
+	const readCredentials = options.readCredentials ?? readStoredCredential;
+	const doFetch = options.fetch ?? globalThis.fetch;
+	const timeoutMs = options.timeoutMs ?? REQUEST_TIMEOUT_MS;
+	const now = options.now ?? (() => new Date());
+
+	const snapshot = (
+		status: UsageSnapshot["status"],
+		message: string | null,
+		extra: Partial<UsageSnapshot> = {},
+	): UsageSnapshot => ({
+		providerId: ANTHROPIC_MAX_QUOTA_PROVIDER_ID,
+		displayName: DISPLAY_NAME,
+		status,
+		windows: [],
+		message,
+		fetchedAt: now().toISOString(),
+		...extra,
+	});
+
+	return {
+		id: ANTHROPIC_MAX_QUOTA_PROVIDER_ID,
+		displayName: DISPLAY_NAME,
+
+		async detect(): Promise<boolean> {
+			return (await readCredentials()) !== null;
+		},
+
+		async fetch(): Promise<UsageSnapshot> {
+			const credentials = await readCredentials();
+			if (credentials === null) {
+				return snapshot("no_credentials", "Clio holds no Anthropic OAuth credential");
+			}
+			if (credentials.expiresAtMs !== null && credentials.expiresAtMs <= now().getTime()) {
+				return snapshot(
+					"expired",
+					credentials.hasRefreshToken
+						? "Clio's Anthropic token expired; the next turn refreshes it"
+						: "Run clio-coder auth login anthropic again",
+				);
+			}
+
+			const usage = await fetchAnthropicUsage(credentials.accessToken, { fetch: doFetch, timeoutMs });
+			if (usage.status !== "ok") {
+				return snapshot(usage.status, usage.message ?? "Run clio-coder auth login anthropic again", {
+					retryAfterSeconds: usage.retryAfterSeconds,
+				});
+			}
+			return snapshot("ok", null, { windows: usage.windows, credits: usage.credits });
+		},
+	};
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asNumber(value: unknown): number | null {
+	if (typeof value === "number") return Number.isFinite(value) ? value : null;
+	if (typeof value === "string") {
+		const parsed = Number.parseFloat(value.trim());
+		return Number.isFinite(parsed) ? parsed : null;
+	}
+	return null;
+}

package/src/domains/quota/anthropic-usage.ts

@@ -0,0 +1,220 @@
+/**
+ * Shared reader for Anthropic's OAuth usage endpoint.
+ *
+ * Two runtimes spend an Anthropic subscription: the `claude-code` CLI with
+ * its own stored login, and `anthropic-max` with the OAuth credential Clio
+ * itself holds. The account surface is the same endpoint and the same two
+ * response shapes, so only the token source differs. This module owns the
+ * request and the parsing; each adapter owns its credential.
+ *
+ * The endpoint has shipped both a `limits[]` array and flat
+ * `five_hour`/`seven_day` buckets, and has been observed serving both at
+ * once. The array wins when present because only it carries severity,
+ * the active flag, and per-model scope.
+ */
+
+import { parseRetryAfterSeconds, type UsageCredits, type UsageSnapshot, type UsageWindow } from "./types.js";
+
+export const ANTHROPIC_USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+export const ANTHROPIC_OAUTH_BETA = "oauth-2025-04-20";
+
+const WINDOW_ORDER: Record<string, number> = { session: 0, weekly: 1 };
+
+/** What one usage read produced, before an adapter stamps its own identity on it. */
+export interface AnthropicUsageOutcome {
+	status: UsageSnapshot["status"];
+	message: string | null;
+	windows: UsageWindow[];
+	credits: UsageCredits | null;
+	retryAfterSeconds: number | null;
+}
+
+export interface AnthropicUsageDependencies {
+	fetch: typeof globalThis.fetch;
+	timeoutMs: number;
+}
+
+function outcome(
+	status: UsageSnapshot["status"],
+	message: string | null,
+	extra: Partial<AnthropicUsageOutcome> = {},
+): AnthropicUsageOutcome {
+	return { status, message, windows: [], credits: null, retryAfterSeconds: null, ...extra };
+}
+
+/** Read current Anthropic usage with a bearer token, reporting failure as a status. */
+export async function fetchAnthropicUsage(
+	token: string,
+	dependencies: AnthropicUsageDependencies,
+): Promise<AnthropicUsageOutcome> {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), dependencies.timeoutMs);
+	let response: Response;
+	try {
+		response = await dependencies.fetch(ANTHROPIC_USAGE_URL, {
+			method: "GET",
+			headers: {
+				Authorization: `Bearer ${token}`,
+				"anthropic-beta": ANTHROPIC_OAUTH_BETA,
+			},
+			signal: controller.signal,
+		});
+	} catch (error) {
+		return outcome("error", describeError(error, dependencies.timeoutMs));
+	} finally {
+		clearTimeout(timer);
+	}
+
+	if (response.status === 401 || response.status === 403) {
+		await discardBody(response);
+		return outcome("expired", null);
+	}
+	if (response.status === 429) {
+		await discardBody(response);
+		return outcome("error", "HTTP 429", {
+			retryAfterSeconds: parseRetryAfterSeconds(response.headers.get("Retry-After")),
+		});
+	}
+	if (response.status !== 200) {
+		await discardBody(response);
+		return outcome("error", `HTTP ${response.status}`);
+	}
+
+	let body: unknown;
+	try {
+		body = await response.json();
+	} catch {
+		return outcome("error", "Unexpected usage response");
+	}
+	if (!isRecord(body)) {
+		return outcome("error", "Unexpected usage response");
+	}
+
+	return outcome("ok", null, { windows: usageWindows(body), credits: usageCredits(body.spend) });
+}
+
+/** Windows from `limits[]` when the endpoint sends it, otherwise the flat buckets. */
+function usageWindows(body: Record<string, unknown>): UsageWindow[] {
+	const fromLimits = windowsFromLimits(body.limits);
+	const windows = fromLimits.length > 0 ? fromLimits : windowsFromFlat(body);
+	return windows.sort((left, right) => {
+		const order = (WINDOW_ORDER[left.key] ?? 2) - (WINDOW_ORDER[right.key] ?? 2);
+		return order !== 0 ? order : left.label.localeCompare(right.label);
+	});
+}
+
+function windowsFromLimits(raw: unknown): UsageWindow[] {
+	if (!Array.isArray(raw)) return [];
+	const windows: UsageWindow[] = [];
+	for (const entry of raw) {
+		if (!isRecord(entry)) continue;
+		const percent = asNumber(entry.percent);
+		if (percent === null) continue;
+		const common: Pick<UsageWindow, "usedPct" | "resetsAt" | "severity" | "active"> = {
+			usedPct: percent,
+			resetsAt: asIsoString(entry.resets_at),
+		};
+		if (typeof entry.severity === "string") common.severity = entry.severity;
+		if (entry.is_active === true) common.active = true;
+		if (entry.kind === "session") {
+			windows.push({ key: "session", label: "5h", short: "5h", ...common });
+		} else if (entry.kind === "weekly_all") {
+			windows.push({ key: "weekly", label: "Weekly", short: "wk", ...common });
+		} else if (entry.kind === "weekly_scoped") {
+			const name = scopeName(entry.scope);
+			if (name === null) continue;
+			windows.push({ key: `weekly_scoped.${slug(name)}`, label: name, scope: name, ...common });
+		}
+	}
+	return windows;
+}
+
+function windowsFromFlat(body: Record<string, unknown>): UsageWindow[] {
+	const windows: UsageWindow[] = [];
+	const fiveHour = bucketWindow(body.five_hour, "session", "5h", "5h");
+	if (fiveHour !== null) windows.push(fiveHour);
+	const sevenDay = bucketWindow(body.seven_day, "weekly", "Weekly", "wk");
+	if (sevenDay !== null) windows.push(sevenDay);
+	return windows;
+}
+
+function bucketWindow(raw: unknown, key: string, label: string, short: string): UsageWindow | null {
+	if (!isRecord(raw)) return null;
+	const usedPct = asNumber(raw.utilization);
+	if (usedPct === null) return null;
+	return { key, label, short, usedPct, resetsAt: asIsoString(raw.resets_at) };
+}
+
+function scopeName(raw: unknown): string | null {
+	if (!isRecord(raw)) return null;
+	const model = raw.model;
+	if (!isRecord(model)) return null;
+	const name = typeof model.display_name === "string" ? model.display_name.trim() : "";
+	if (name.length === 0) return null;
+	return slug(name) === "all-models" || slug(name) === "all" ? null : name;
+}
+
+/** Credit balance from the `spend` block, present only for credit-billed plans. */
+function usageCredits(raw: unknown): UsageCredits | null {
+	if (!isRecord(raw) || raw.enabled !== true) return null;
+	const percent = asNumber(raw.percent);
+	const limit = majorAmount(raw.limit);
+	if (limit === null) {
+		return percent === null ? null : { display: `${percent.toFixed(0)}% used`, usedPct: percent };
+	}
+	const used = majorAmount(raw.used);
+	if (used === null) return null;
+	const currency = isRecord(raw.limit) && typeof raw.limit.currency === "string" ? raw.limit.currency : "USD";
+	const symbol = currency === "USD" ? "$" : "";
+	const usedPct = percent ?? (limit > 0 ? (used / limit) * 100 : null);
+	return { display: `${symbol}${used.toFixed(2)} / ${symbol}${limit.toFixed(2)}`, usedPct };
+}
+
+function majorAmount(raw: unknown): number | null {
+	if (!isRecord(raw)) return null;
+	const minor = asNumber(raw.amount_minor);
+	if (minor === null) return null;
+	const exponent = asNumber(raw.exponent) ?? 0;
+	return minor / 10 ** exponent;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asNumber(value: unknown): number | null {
+	if (typeof value === "number") return Number.isFinite(value) ? value : null;
+	if (typeof value === "string") {
+		const parsed = Number.parseFloat(value.trim());
+		return Number.isFinite(parsed) ? parsed : null;
+	}
+	return null;
+}
+
+function asIsoString(value: unknown): string | null {
+	if (typeof value !== "string" || value.trim().length === 0) return null;
+	const parsed = new Date(value);
+	return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString();
+}
+
+function slug(value: string): string {
+	return value
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+}
+
+function describeError(error: unknown, timeoutMs: number): string {
+	if (error instanceof Error) {
+		return error.name === "AbortError" ? `timeout after ${timeoutMs}ms` : error.message;
+	}
+	return String(error);
+}
+
+async function discardBody(response: Response): Promise<void> {
+	try {
+		await response.body?.cancel();
+	} catch {
+		return;
+	}
+}