@stemtrooper/learningcode 0.3.1 → 0.4.0

package/README.md

@@ -114,12 +114,19 @@ Useful commands, typed inside the session:
 | `/help` | list everything available |
 | `/quota` | your token spend today |
 | `/seats` | how many seats are free |
+| `/spark-login` | check your TLC-Spark token, or find out how to get a new one |
 | `/model` | switch model |
 | `/hotkeys` | keyboard shortcuts |
 
-`/quota` and `/seats` talk to Spark directly. They are the two commands a stock
-AI coding tool does not have, because those endpoints are not part of any public
-API.
+`/quota`, `/seats` and `/spark-login` talk to Spark directly. They are the commands a
+stock AI coding tool does not have, because those endpoints are not part of any
+public API.
+
+**Getting a new TLC-Spark token.** Use `/spark-login` to check the one you have;
+it tells you whether Spark still accepts it. To actually replace it, exit and run
+`learningcode --login`, which prompts without echoing. It is deliberately *not* a
+`/` command: typing a token into the agent's own input box would leave it in your
+scrollback, which is the wrong thing to do on a shared lab machine.
 
 One-off, non-interactive:
 

package/extensions/spark-quota.ts

@@ -1,4 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { cachedTokenPrefix } from "../lib/token.mjs";
+import { agentDir } from "../lib/config.mjs";
 
 /**
  * Spark-aware status for the learningcode client.
@@ -17,13 +19,13 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 const BASE_URL = (process.env.SPARK_BASE_URL || "https://spark.learning.com.my/v1").replace(/\/+$/, "");
 const TOKEN = process.env.SPARK_API_KEY || "";
 
-async function call(path: string): Promise<{ ok: true; body: unknown } | { ok: false; error: string }> {
+async function call(path: string): Promise<{ ok: true; body: unknown } | { ok: false; error: string; status?: number }> {
 	if (!TOKEN) return { ok: false, error: "no Spark token in the environment" };
 	try {
 		const response = await fetch(`${BASE_URL}${path}`, {
 			headers: { Authorization: `Bearer ${TOKEN}` },
 		});
-		if (!response.ok) return { ok: false, error: `HTTP ${response.status}` };
+		if (!response.ok) return { ok: false, error: `HTTP ${response.status}`, status: response.status };
 		return { ok: true, body: await response.json() };
 	} catch (error) {
 		return { ok: false, error: error instanceof Error ? error.message : "unreachable" };
@@ -85,6 +87,71 @@ export default function sparkQuota(pi: ExtensionAPI) {
 		},
 	});
 
+	/**
+	 * Check the TLC-Spark token and say what to do about it.
+	 *
+	 * This deliberately does not accept a pasted token. Two constraints make that
+	 * the wrong place to type a secret:
+	 *
+	 *   - Pi's input dialog has no mask option, so the value would sit in scrollback
+	 *     in plain text, which on a shared lab machine is worse than the masked
+	 *     prompt `learningcode --login` already uses.
+	 *   - Pi caches resolved environment values, so a token set mid-session would
+	 *     not reliably take effect until the next launch anyway.
+	 *
+	 * So this reports whether the token Spark is actually seeing is still good,
+	 * which is the question a student has after rotating it, and points at the
+	 * command that does the work.
+	 */
+	pi.registerCommand("spark-login", {
+		description: "Check your TLC-Spark token, or get a new one",
+		handler: async (_args, ctx) => {
+			const prefix = await cachedTokenPrefix(agentDir()).catch(() => undefined);
+
+			if (!TOKEN) {
+				ctx.ui.notify(
+					"No TLC-Spark token loaded. Exit and run:  learningcode --login",
+					"warning",
+				);
+				return;
+			}
+
+			const result = await call("/me/quota");
+
+			if (result.ok) {
+				const body = result.body as Record<string, unknown>;
+				const used = num(body.tokensUsed);
+				const limit = num(body.dailyTokenLimit);
+				ctx.ui.notify(
+					[
+						`Token OK${prefix ? ` (${prefix}…)` : ""}`,
+						`${used.toLocaleString()}/${limit.toLocaleString()} tokens today`,
+						"Rotating it? Exit and run:  learningcode --login",
+					].join("  |  "),
+					"info",
+				);
+				return;
+			}
+
+			if (result.status === 401 || result.status === 403) {
+				ctx.ui.notify(
+					[
+						`Spark rejected your token${prefix ? ` (${prefix}…)` : ""}.`,
+						"It was probably rotated, which revokes the old one.",
+						"Exit and run:  learningcode --login",
+					].join(" "),
+					"warning",
+				);
+				return;
+			}
+
+			ctx.ui.notify(
+				`Cannot reach Spark at ${BASE_URL} (${result.error}). Check your network.`,
+				"warning",
+			);
+		},
+	});
+
 	// One check at startup rather than after every turn: the quota moves by at
 	// most one request per turn, and a fetch on each `agent_end` would add
 	// latency to the thing students are waiting on.

package/lib/token.mjs

@@ -121,4 +121,16 @@ export async function hasToken(agentDir, explicit) {
 	return Boolean(await readCachedToken(agentDir));
 }
 
+/**
+ * The leading fragment of the cached token, for display only.
+ *
+ * Spark keeps `raw.slice(0, 18)` as tokenPrefix for the same reason, so showing
+ * this much identifies a token without disclosing it. Nothing here ever returns
+ * the full value.
+ */
+export async function cachedTokenPrefix(agentDir, length = 18) {
+	const token = await readCachedToken(agentDir);
+	return token ? token.slice(0, length) : undefined;
+}
+
 export { writeCachedToken };

package/package.json

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