@stemtrooper/learningcode 0.4.4 → 0.4.6

package/README.md

@@ -1,4 +1,13 @@
-# learningcode
+```text
+██╗     ███████╗ █████╗ ██████╗ ███╗   ██╗██╗███╗   ██╗ ██████╗  ██████╗ ██████╗ ██████╗ ███████╗
+██║     ██╔════╝██╔══██╗██╔══██╗████╗  ██║██║████╗  ██║██╔════╝ ██╔════╝██╔═══██╗██╔══██╗██╔════╝
+██║     █████╗  ███████║██████╔╝██╔██╗ ██║██║██╔██╗ ██║██║  ███╗██║     ██║   ██║██║  ██║█████╗
+██║     ██╔══╝  ██╔══██║██╔══██╗██║╚██╗██║██║██║╚██╗██║██║   ██║██║     ██║   ██║██║  ██║██╔══╝
+███████╗███████╗██║  ██║██║  ██║██║ ╚████║██║██║ ╚████║╚██████╔╝╚██████╗╚██████╔╝██████╔╝███████╗
+╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═╝╚═╝  ╚═══╝ ╚═════╝  ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝
+```
+
+*The Learning Curve · Sarawak*
 
 A terminal coding agent for **The Learning Curve** students, running on TLC's own
 inference through **TLC-Spark**.
@@ -171,10 +180,6 @@ learningcode --mode json           # machine-readable output
 The TLC brand theme and banner ship with the package, so there is nothing to
 configure.
 
-LearningCode suppresses Pi's built-in startup header so the TLC banner appears
-without the Pi logo flashing first. Use `learningcode --verbose` to show Pi's
-startup details and loaded-resource list as well.
-
 ```
   ██╗     ███████╗ █████╗ ██████╗ ███╗   ██╗██╗███╗   ██╗ ██████╗  ██████╗ ██████╗ ██████╗ ███████╗
   ██║     ██╔════╝██╔══██╗██╔══██╗████╗  ██║██║████╗  ██║██╔════╝ ██╔════╝██╔═══██╗██╔══██╗██╔════╝
@@ -188,12 +193,22 @@ startup details and loaded-resource list as well.
 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
@@ -243,7 +258,7 @@ to Spark, and no telemetry is sent.
 learningcode --show-config     # show resolved paths and settings
 learningcode --login           # enter a new token
 learningcode --list-models     # every reachable model
-learningcode --theme dark      # use the upstream theme instead of TLC's
+learningcode --use-theme dark   # use the upstream theme instead of TLC's
 ```
 
 **Your edits are kept.** If you change the theme or the model configuration,

package/bin/learningcode.mjs

@@ -240,13 +240,22 @@ async function main() {
 	const effectiveModel = requestedModel ?? `${PROVIDER_ID}/${MODEL_ID}`;
 	if (!requestedModel) forced.push("--model", effectiveModel);
 
-	// Default to the TLC theme, but never override an explicit choice: --theme on
-	// the command line, or LEARNINGCODE_THEME in the environment.
+	// Default to the TLC theme without overriding an explicit CLI choice.
+	// LEARNINGCODE_THEME flows through preferredTheme(), so it becomes the
+	// forced value rather than suppressing it. NB: Pi's --theme loads a theme
+	// *file or directory*, while --use-theme selects a theme *by name*.
+	// Passing "tlc-dark" to --theme made Pi warn "[Theme conflicts] ...
+	// theme path does not exist" on every login, so the name goes to
+	// --use-theme.
 	const userPickedTheme = toPi.some(
-		(arg) => arg === "--theme" || arg.startsWith("--theme="),
+		(arg) =>
+			arg === "--theme" ||
+			arg.startsWith("--theme=") ||
+			arg === "--use-theme" ||
+			arg.startsWith("--use-theme="),
 	);
-	if (!userPickedTheme && !process.env.LEARNINGCODE_THEME) {
-		forced.push("--theme", preferredTheme());
+	if (!userPickedTheme) {
+		forced.push("--use-theme", preferredTheme());
 	}
 
 	// Spark enforces one active generation per student, so subagents and parallel

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/themes.mjs

@@ -39,7 +39,7 @@ export function preferredTheme(env = process.env) {
 	if (forced) return forced;
 	// Windows Terminal defaults to a dark scheme for most profiles; macOS and
 	// Linux terminals are more often light. This is a guess either way, which is
-	// why an explicit --theme still wins.
+	// why an explicit --use-theme still wins.
 	return env.LEARNINGCODE_LIGHT_THEME === "1" ? "tlc-light" : "tlc-dark";
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@stemtrooper/learningcode",
-	"version": "0.4.4",
+	"version": "0.4.6",
 	"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",