@stemtrooper/learningcode 0.4.3 → 0.4.5

package/README.md

@@ -184,12 +184,22 @@ configure.
 On a narrower terminal it steps down to a condensed banner, then to the wordmark,
 rather than drawing art that would be clipped.
 
+LearningCode suppresses Pi's built-in startup header so its own banner appears
+without the Pi logo flashing first. Use `learningcode --verbose` to show Pi's
+startup header and loaded-resource list as well. An explicit `quietStartup`
+setting in `~/.learningcode/agent/settings.json` is respected.
+
 A footer shows your remaining quota whenever you are connected to Spark:
 
 ```
   █████░░░░░ 50%  125k / 250k today
 ```
 
+Quota-exempt accounts show `unlimited`. An account with no daily token cap but
+still subject to a weekly cap shows `no daily token cap` instead; Spark reports
+those as different states, and the client must not mistake a missing daily
+limit for either zero allowance or unlimited use.
+
 ---
 
 ## Troubleshooting
@@ -297,4 +307,4 @@ is also MIT. See [LICENSE](LICENSE).
 
 Not affiliated with, endorsed by, or connected to Pi, OpenCode, Anomaly, or any of
 the model providers reachable through this client. "The Learning Curve", TLC and
-Spark are trademarks of The Learning Curve.
+Spark are trademarks of The Learning Curve.

package/bin/learningcode.mjs

@@ -17,6 +17,7 @@ import {
 } from "../lib/config.mjs";
 import { GO_PROVIDER, saveProviderKey } from "../lib/auth.mjs";
 import { ensureSparkProvider, modelsPath, retargetProvider } from "../lib/models.mjs";
+import { ensureQuietStartup } from "../lib/settings.mjs";
 import { ensureThemes, preferredTheme } from "../lib/themes.mjs";
 import { hasToken, looksLikeToken, resolveToken, writeCachedToken } from "../lib/token.mjs";
 
@@ -45,6 +46,7 @@ Everything else is passed straight through to Pi, so the usual flags work:
   learningcode -p "explain main.py"   one-shot, non-interactive
   learningcode --mode json            machine-readable event stream
   learningcode --list-models          every model Pi can reach
+  learningcode --verbose              show Pi's startup header and resource list
 
 Other providers
   Any --model other than tlc-spark/... skips the Spark token and the Spark
@@ -230,6 +232,7 @@ async function main() {
 	}
 	await ensureSparkProvider(dir);
 	await ensureThemes(dir);
+	await ensureQuietStartup(dir);
 
 	// `--login` forces a fresh paste even when a token is already cached.
 	const forced = [];
@@ -369,4 +372,4 @@ main().catch((error) => {
 	// Anything the user can act on gets one line. A stack trace is noise for a
 	// student who mistyped a token; keep it for genuine bugs.
 	fail(error instanceof UserError ? error.message : error?.stack || String(error));
-});
+});

package/extensions/footer.ts

@@ -24,7 +24,13 @@ const TOKEN = process.env.SPARK_API_KEY || "";
 /** Two minutes. Enough to stay current, rarely enough to be invisible. */
 const POLL_MS = 120_000;
 
-type Quota = { tokensUsed: number; dailyTokenLimit: number; aiEnabled: boolean };
+type Quota = {
+  tokensUsed: number;
+  /** null means no daily cap, which is not the same as a cap of zero. */
+  dailyTokenLimit: number | null;
+  quotaExempt?: boolean;
+  aiEnabled: boolean;
+};
 
 const num = (value: unknown): number =>
   typeof value === "number" && Number.isFinite(value) ? value : 0;
@@ -32,6 +38,9 @@ const num = (value: unknown): number =>
 const pct = (used: number, limit: number): string =>
   limit > 0 ? `${Math.min(100, Math.round((used / limit) * 100))}%` : "--";
 
+/** Only Spark's explicit exemption removes every token ceiling. */
+const isUnlimited = (quota: Quota): boolean => quota.quotaExempt === true;
+
 /**
  * A ten cell meter. Text alone ("82%") is easy to skim past; a bar is read at a
  * glance, which is the entire reason this is a footer rather than a command.
@@ -44,10 +53,22 @@ function meter(used: number, limit: number, width = 10): string {
 
 function format(quota: Quota): string[] {
   if (quota.aiEnabled === false) return ["AI off — ask your teacher"];
-  const { tokensUsed, dailyTokenLimit } = quota;
+  const { tokensUsed } = quota;
+
+  if (isUnlimited(quota)) {
+    // No bar and no percentage: a full meter would imply a ceiling that is not
+    // there, and any percentage of infinity is noise.
+    return [`${Math.round(tokensUsed / 1000)}k used today  ·  unlimited`];
+  }
+
+  if (quota.dailyTokenLimit === null || quota.dailyTokenLimit === undefined) {
+    return [`${Math.round(tokensUsed / 1000)}k used today  ·  no daily token cap`];
+  }
+
+  const limit = num(quota.dailyTokenLimit);
   return [
-    `${meter(tokensUsed, dailyTokenLimit)} ${pct(tokensUsed, dailyTokenLimit)}`,
-    `${Math.round(tokensUsed / 1000)}k/${Math.round(dailyTokenLimit / 1000)}k today`,
+    `${meter(tokensUsed, limit)} ${pct(tokensUsed, limit)}`,
+    `${Math.round(tokensUsed / 1000)}k/${Math.round(limit / 1000)}k today`,
   ];
 }
 
@@ -95,9 +116,28 @@ export default function sparkFooter(pi: ExtensionAPI) {
             return [theme.fg("error", "  AI disabled for your account — ask your teacher")];
           }
 
+          // No ceiling: no meter and no percentage, because a full bar implies a
+          // limit that does not exist.
+          if (isUnlimited(quota)) {
+            return [
+              theme.fg("dim", `  ${Math.round(quota.tokensUsed / 1000)}k used today`) +
+                theme.fg("muted", "  ·  unlimited"),
+            ];
+          }
+
+          // A null daily cap does not mean unlimited: the weekly cap can still
+          // apply. Do not turn null into zero or show a misleading /0K allowance.
+          if (quota.dailyTokenLimit === null || quota.dailyTokenLimit === undefined) {
+            return [
+              theme.fg("dim", `  ${Math.round(quota.tokensUsed / 1000)}k used today`) +
+                theme.fg("muted", "  ·  no daily token cap"),
+            ];
+          }
+
           const { tokensUsed, dailyTokenLimit } = quota;
-          const bar = theme.fg("accent", meter(tokensUsed, dailyTokenLimit));
-          const percent = theme.fg("muted", pct(tokensUsed, dailyTokenLimit));
+          const limit = dailyTokenLimit;
+          const bar = theme.fg("accent", meter(tokensUsed, limit));
+          const percent = theme.fg("muted", pct(tokensUsed, limit));
 
           // Narrow terminals keep the bar and the percentage only; the absolute
           // token counts are the part that can be dropped.
@@ -105,7 +145,7 @@ export default function sparkFooter(pi: ExtensionAPI) {
 
           const numbers = theme.fg(
             "dim",
-            `${Math.round(tokensUsed / 1000)}k / ${Math.round(dailyTokenLimit / 1000)}k today`,
+            `${Math.round(tokensUsed / 1000)}k / ${Math.round(limit / 1000)}k today`,
           );
           return [`  ${bar} ${percent}  ${numbers}`];
         },
@@ -125,4 +165,4 @@ export default function sparkFooter(pi: ExtensionAPI) {
 }
 
 // Exported for tests.
-export const _internals = { format, meter, pct };
+export const _internals = { format, isUnlimited, meter, pct };

package/extensions/spark-quota.ts

@@ -34,9 +34,46 @@ async function call(path: string): Promise<{ ok: true; body: unknown } | { ok: f
 
 const num = (value: unknown): number => (typeof value === "number" && Number.isFinite(value) ? value : 0);
 
-function quotaLine(body: Record<string, unknown>): string {
+type QuotaBody = {
+	day?: string;
+	tokensUsed?: number;
+  dailyTokenLimit?: number | null;
+  jobsUsed?: number;
+  dailyJobLimit?: number | null;
+  quotaExempt?: boolean;
+  aiEnabled?: boolean;
+};
+
+/** Only Spark's explicit exemption removes every token ceiling. */
+const isUnlimited = (body: QuotaBody): boolean => body.quotaExempt === true;
+
+const thousands = (value: number): string => `${Math.round(value / 1000)}k`;
+
+function quotaLine(body: QuotaBody): string {
 	const used = num(body.tokensUsed);
-	const limit = num(body.dailyTokenLimit);
+	if (isUnlimited(body)) {
+		return [
+			`Spark quota - ${used.toLocaleString()} tokens used, unlimited`,
+			"exempt",
+			`jobs ${num(body.jobsUsed)}`,
+			`day ${String(body.day ?? "?")}`,
+			body.aiEnabled === false ? "AI DISABLED for your account - ask your teacher" : "",
+		]
+			.filter(Boolean)
+			.join("  |  ");
+	}
+	if (body.dailyTokenLimit === null || body.dailyTokenLimit === undefined) {
+		return [
+			`Spark quota - ${used.toLocaleString()} tokens used today, no daily token cap`,
+			`jobs ${num(body.jobsUsed)}/${num(body.dailyJobLimit)}`,
+			`day ${String(body.day ?? "?")}`,
+			body.aiEnabled === false ? "AI DISABLED for your account - ask your teacher" : "",
+		]
+			.filter(Boolean)
+			.join("  |  ");
+	}
+
+	const limit = body.dailyTokenLimit;
 	const pct = limit > 0 ? ` (${Math.round((used / limit) * 100)}%)` : "";
 	return [
 		`Spark quota - ${used.toLocaleString()}/${limit.toLocaleString()} tokens${pct}`,
@@ -48,6 +85,8 @@ function quotaLine(body: Record<string, unknown>): string {
 		.join("  |  ");
 }
 
+export const _internals = { quotaLine, isUnlimited, thousands, num };
+
 /**
  * The queue view shape is not guaranteed, so surface the fields we recognise
  * and fall back to raw JSON rather than inventing structure.
@@ -70,7 +109,7 @@ export default function sparkQuota(pi: ExtensionAPI) {
 		handler: async (_args, ctx) => {
 			const result = await call("/me/quota");
 			ctx.ui.notify(
-				result.ok ? quotaLine(result.body as Record<string, unknown>) : `quota unavailable: ${result.error}`,
+				result.ok ? quotaLine(result.body as QuotaBody) : `quota unavailable: ${result.error}`,
 				result.ok ? "info" : "warning",
 			);
 		},
@@ -177,4 +216,4 @@ export default function sparkQuota(pi: ExtensionAPI) {
 			);
 		}
 	});
-}
+}

package/lib/settings.mjs

@@ -0,0 +1,42 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { UserError } from "./config.mjs";
+
+/**
+ * Pi renders its built-in header before extension `session_start` handlers run.
+ * Its supported quietStartup setting prevents that header flashing before the
+ * LearningCode banner is installed. Only seed the setting when it is unset, so
+ * an explicit choice in the student's LearningCode settings remains theirs.
+ */
+export async function ensureQuietStartup(agentDir) {
+	const path = join(agentDir, "settings.json");
+	let settings;
+
+	try {
+		const contents = await readFile(path, "utf-8");
+		try {
+			settings = JSON.parse(contents.replace(/^\uFEFF/, ""));
+		} catch (error) {
+			throw new UserError(`Could not parse Pi settings at ${path}: ${error.message}`);
+		}
+	} catch (error) {
+		if (error instanceof UserError) throw error;
+		if (error?.code !== "ENOENT") {
+			throw new UserError(`Could not read Pi settings at ${path}: ${error.message}`);
+		}
+		settings = {};
+	}
+
+	if (!settings || typeof settings !== "object" || Array.isArray(settings)) {
+		throw new UserError(`Pi settings at ${path} must contain a JSON object.`);
+	}
+
+	if (typeof settings.quietStartup === "boolean" || settings.quietStartup === "header") {
+		return false;
+	}
+
+	settings.quietStartup = true;
+	await mkdir(agentDir, { recursive: true });
+	await writeFile(path, `${JSON.stringify(settings, null, 2)}\n`, "utf-8");
+	return true;
+}

package/package.json

@@ -1,11 +1,11 @@
 {
 	"name": "@stemtrooper/learningcode",
-	"version": "0.4.3",
+	"version": "0.4.5",
 	"description": "TLC Spark coding agent for students: Pi wired to the Spark OpenAI-compatible endpoint with per-student tokens, quota and seat-queue awareness.",
 	"type": "module",
 	"license": "MIT",
 	"bin": {
-		"learningcode": "./bin/learningcode.mjs"
+		"learningcode": "bin/learningcode.mjs"
 	},
 	"files": [
 		"assets",