@stemtrooper/learningcode 0.4.4 → 0.4.5

package/README.md

@@ -171,10 +171,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 +184,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

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/package.json

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