@stemtrooper/learningcode 0.1.0

package/LICENSE

@@ -0,0 +1,49 @@
+MIT License
+
+Copyright (c) 2026 TLC (The Learning Curve) / stemtrooper
+
+learningcode is a distribution wrapper. It does not contain source copied from
+Pi; it depends on @earendil-works/pi-coding-agent at runtime.
+
+That dependency is MIT licensed:
+
+    MIT License
+    Copyright (c) Mario Zechner (and contributors)
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE.
+
+The MIT licence terms below govern learningcode itself.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# learningcode
+
+A terminal coding agent for TLC students, wired to [Spark](../spark) — the
+inference gateway that holds per-student tokens, timetable policy, seat limits
+and weekly quota.
+
+Students run one command:
+
+```bash
+npm i -g @stemtrooper/learningcode
+learningcode
+```
+
+On first run it asks for the personal `spark_live_` token from the Spark bench,
+caches it with `0600`, writes the TLC-Spark provider config, and hands off to
+Pi with the model pinned.
+
+```
+baseURL  https://spark.learning.com.my/v1
+model    TLC-Spark
+```
+
+## What students get
+
+Pi's four built-in tools — `read`, `bash`, `edit`, `write` — against
+Qwen3.8-27B. Two extra commands, because Spark is not a plain OpenAI endpoint:
+
+| Command | Why it exists |
+|---|---|
+| `/quota` | Tokens used against today's limit, and whether AI is enabled for your account |
+| `/seats` | Live seat queue, so a student can see why a turn is waiting |
+
+`session_start` also warns once if you cross 80% of your daily quota or if a
+teacher has switched AI off for your account.
+
+## Why not just ship Pi?
+
+Because Spark's limits are the design constraint, not the model:
+
+- **32K max context, 16K default.** Agent sessions burn this fast. `learningcode`
+  starts Pi with `--no-skills`, since skills are pure prompt-token spend.
+- **One active generation per student.** Subagents and parallel tool calls would
+  only earn `429`s. Pi is serial by default and this wrapper does not turn that off.
+- **250K tokens per week.** Frugality is the product, so the budget is visible
+  instead of mysterious.
+
+Stock Pi does not know `/v1/me/quota` or `/v1/queue` exist. That gap is the whole
+reason this wrapper exists.
+
+## Configuration
+
+`~/.learningcode/agent/models.json` is created on first run and **never
+overwritten** — local edits survive upgrades. The provider is seeded with these
+compatibility flags, each of which matches a field Spark either rejects or drops:
+
+| Flag | Value | Spark behaviour |
+|---|---|---|
+| `supportsDeveloperRole` | `false` | message union is `system \| user \| assistant \| tool`; there is no `developer` |
+| `maxTokensField` | `"max_tokens"` | `v1.ts` reads `body.max_tokens` only |
+| `supportsReasoningEffort` | `false` | not forwarded to the runtime |
+| `supportsStore` | `false` | not implemented |
+
+Environment variables:
+
+| Variable | Purpose |
+|---|---|
+| `LEARNINGCODE_DIR` | agent directory (default `~/.learningcode/agent`) |
+| `LEARNINGCODE_SPARK_BASE_URL` | point at another Spark deployment |
+| `LEARNINGCODE_TOKEN` | Spark token, skips the cached file |
+| `LEARNINGCODE_PI_FLAGS` | extra flags appended to every launch |
+
+```bash
+learningcode --show-config      # resolved paths, model, token prefix
+learningcode --base-url http://localhost:3000/v1   # local bench
+learningcode --login            # re-enter a rotated token
+learningcode -c                 # continue last session
+learningcode -p "explain main.py"
+learningcode --mode json        # machine-readable event stream
+```
+
+Anything not listed as a `learningcode` flag is passed straight to Pi.
+
+## Pinning
+
+`@earendil-works/pi-coding-agent` is pinned to an exact version, not a range. Pi
+ships breaking changes daily, and a student's install must not change underneath
+them mid-term. Bump it deliberately, after testing against a live pod.
+
+## Licence
+
+MIT. Depends on Pi, also MIT. See [LICENSE](LICENSE).

package/bin/learningcode.mjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	MODEL_ID,
+	PI_AGENT_DIR_ENV,
+	PROVIDER_ID,
+	TOKEN_ENV,
+	UserError,
+	agentDir,
+	sparkBaseUrl,
+} from "../lib/config.mjs";
+import { ensureSparkProvider, modelsPath, retargetProvider } from "../lib/models.mjs";
+import { hasToken, looksLikeToken, resolveToken, writeCachedToken } from "../lib/token.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+const OWN_FLAGS = new Set(["--help", "-h", "--version", "-v", "--login", "--show-config"]);
+const OWN_FLAGS_WITH_VALUE = new Set(["--token", "--base-url"]);
+
+const HELP = `learningcode - TLC Spark coding agent
+
+Usage
+  learningcode [options] [pi options] [@files...] [message...]
+
+Setup
+  --token <tok>      Use this Spark token instead of the cached one
+  --base-url <url>   Point TLC-Spark at a different Spark deployment
+  --login            Re-enter and cache your Spark token
+  --show-config      Print resolved paths and settings, then exit
+  -h, --help         Show this help
+  -v, --version      Show version
+
+Everything else is passed straight through to Pi, so the usual flags work:
+
+  learningcode -c                     continue the last session
+  learningcode -p "explain main.py"   one-shot, non-interactive
+  learningcode --mode json            machine-readable event stream
+  learningcode --list-models          every model Pi can reach
+
+Other providers
+  Any --model other than tlc-spark/... skips the Spark token and the Spark
+  health check, so you can work without a token or while Spark is down:
+
+  export OPENCODE_API_KEY=...
+  learningcode --model opencode-go/glm-5.3-flash
+  learningcode --list-models opencode
+
+Environment
+  LEARNINGCODE_DIR            agent directory (default ~/.learningcode/agent)
+  LEARNINGCODE_SPARK_BASE_URL default https://spark.learning.com.my/v1
+  LEARNINGCODE_TOKEN          Spark token, skips the cached file
+  LEARNINGCODE_PI_FLAGS       extra flags appended to every Pi launch
+  OPENCODE_API_KEY            auth for the opencode-go / opencode-zen providers
+  ${PI_AGENT_DIR_ENV}  set automatically; points Pi at the learningcode agent dir
+`;
+
+/** Split our flags from the ones meant for Pi. */
+function parseArgs(argv) {
+	const own = { help: false, version: false, login: false, showConfig: false };
+	const toPi = [];
+	let explicitToken;
+	let baseUrl;
+
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+
+		if (OWN_FLAGS.has(arg)) {
+			if (arg === "--help" || arg === "-h") own.help = true;
+			if (arg === "--version" || arg === "-v") own.version = true;
+			if (arg === "--login") own.login = true;
+			if (arg === "--show-config") own.showConfig = true;
+			continue;
+		}
+
+		if (OWN_FLAGS_WITH_VALUE.has(arg)) {
+			const value = argv[i + 1];
+			if (!value || value.startsWith("-")) {
+				fail(`${arg} requires a value.`);
+			}
+			i += 1;
+			if (arg === "--token") explicitToken = value;
+			if (arg === "--base-url") baseUrl = value;
+			continue;
+		}
+
+		// Support --token=value / --base-url=value.
+		const eq = arg.indexOf("=");
+		if (arg.startsWith("--") && eq > 0) {
+			const name = arg.slice(0, eq);
+			if (OWN_FLAGS_WITH_VALUE.has(name)) {
+				if (name === "--token") explicitToken = arg.slice(eq + 1);
+				if (name === "--base-url") baseUrl = arg.slice(eq + 1);
+				continue;
+			}
+		}
+
+		toPi.push(arg);
+	}
+
+	return { own, toPi, explicitToken, baseUrl };
+}
+
+/** The model spec the caller asked for, in either `--model X` or `--model=X` form. */
+function readModel(toPi) {
+	for (let i = 0; i < toPi.length; i += 1) {
+		if (toPi[i] === "--model" && toPi[i + 1]) return toPi[i + 1];
+		if (toPi[i].startsWith("--model=")) return toPi[i].slice("--model=".length);
+	}
+	return undefined;
+}
+
+function fail(message, code = 1) {
+	process.stderr.write(`learningcode: ${message}\n`);
+	process.exit(code);
+}
+
+/**
+ * Locate Pi's bundled CLI entry. Going through the resolved package entry keeps
+ * this working on Windows, where the .bin shim is a .cmd file that cannot be
+ * spawned directly without a shell.
+ *
+ * Must use `import.meta.resolve`: the published package declares only an
+ * `import` condition in its exports map, so `require.resolve` fails with
+ * ERR_PACKAGE_PATH_NOT_EXPORTED.
+ */
+function resolvePiEntry() {
+	const candidates = [];
+
+	try {
+		const entry = fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"));
+		candidates.push(join(dirname(entry), "bundle", "cli.js"));
+	} catch {
+		/* fall through to the node_modules walk below */
+	}
+
+	// Walk up from this file in case resolution was blocked (odd global layouts,
+	// pnpm-style stores, a bundled single-file install).
+	let dir = here;
+	for (let depth = 0; depth < 8; depth += 1) {
+		candidates.push(
+			join(dir, "node_modules", "@earendil-works", "pi-coding-agent", "dist", "bundle", "cli.js"),
+		);
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+
+	return candidates.find((candidate) => existsSync(candidate)) ?? null;
+}
+
+/** Non-fatal reachability probe so students get a useful message, not a stack trace. */
+async function checkEndpoint(baseUrl, token) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), 5000);
+	try {
+		const response = await fetch(`${baseUrl}/models`, {
+			headers: { Authorization: `Bearer ${token}` },
+			signal: controller.signal,
+		});
+		if (response.ok) return { ok: true };
+		if (response.status === 401) return { ok: false, reason: "token rejected (401)" };
+		return { ok: false, reason: `HTTP ${response.status}` };
+	} catch (error) {
+		const reason = error?.name === "AbortError" ? "timed out after 5s" : error?.message;
+		return { ok: false, reason };
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+async function main() {
+	const argv = process.argv.slice(2);
+	const { own, toPi, explicitToken, baseUrl } = parseArgs(argv);
+
+	if (own.help) {
+		process.stdout.write(HELP);
+		return;
+	}
+
+	const { version } = require("../package.json");
+	if (own.version) {
+		process.stdout.write(`${version}\n`);
+		return;
+	}
+
+	const dir = agentDir();
+	const piEntry = resolvePiEntry();
+	if (!piEntry) {
+		fail(
+			"could not locate @earendil-works/pi-coding-agent.\n" +
+				"Reinstall with: npm i -g @stemtrooper/learningcode",
+		);
+	}
+
+	if (baseUrl) {
+		await ensureSparkProvider(dir).catch(() => {});
+		await retargetProvider(dir, baseUrl);
+	}
+	await ensureSparkProvider(dir);
+
+	// `--login` forces a fresh paste even when a token is already cached.
+	const forced = [];
+	const requestedModel = readModel(toPi);
+	const effectiveModel = requestedModel ?? `${PROVIDER_ID}/${MODEL_ID}`;
+	if (!requestedModel) forced.push("--model", effectiveModel);
+	// Spark enforces one active generation per student, so subagents and parallel
+	// tool calls would only earn 429s. Pi is serial by default; skills and rules
+	// are pure prompt-token spend against a 32K ceiling, so they stay off.
+	forced.push("--no-skills");
+	forced.push("--extension", join(here, "..", "extensions", "spark-quota.ts"));
+	if (process.env.LEARNINGCODE_PI_FLAGS) {
+		forced.push(...process.env.LEARNINGCODE_PI_FLAGS.split(/\s+/).filter(Boolean));
+	}
+
+	// Everything Spark-specific is skipped when another provider is selected, so
+	// `learningcode --model opencode-go/...` keeps working while Spark or your RunPod
+	// is down, and without holding a token. `--list-models` only enumerates what Pi
+	// can reach and makes no request, so it never needs a Spark token either.
+	const listsModels = toPi.includes("--list-models") || toPi.some((arg) => arg.startsWith("--list-models="));
+	const usesSpark = !listsModels && effectiveModel.startsWith(`${PROVIDER_ID}/`);
+	let token;
+	let tokenSource = "not required";
+
+	if (usesSpark) {
+		// With no token anywhere, a bare `learningcode` opens a prompt that looks like a
+		// dead end. Name the hosted escape hatch before asking.
+		if (!(await hasToken(dir, own.login ? undefined : explicitToken))) {
+			process.stderr.write(
+				"No Spark token configured, defaulting to " +
+					`${PROVIDER_ID}/${MODEL_ID}.\n` +
+					"  Using OpenCode Go instead?  learningcode --model opencode-go/glm-5.3-flash\n" +
+					"  Full list:               learningcode --list-models opencode-go\n",
+			);
+		}
+
+		const resolved = await resolveToken(dir, own.login ? undefined : explicitToken);
+		token = resolved.token;
+		tokenSource = resolved.source;
+
+		if (!looksLikeToken(token)) {
+			process.stderr.write(
+				'learningcode: warning - token does not start with "spark_live_"; ' +
+					"it may not be a Spark token.\n",
+			);
+		}
+		if (resolved.shouldCache) await writeCachedToken(dir, token);
+	} else if (explicitToken) {
+		process.stderr.write(
+			`learningcode: --token only applies to ${PROVIDER_ID}; ignoring it for ${effectiveModel}.\n`,
+		);
+	}
+
+	if (own.showConfig) {
+		process.stdout.write(
+			`version      ${version}\n` +
+				`agent dir    ${dir}\n` +
+				`models.json  ${modelsPath(dir)}\n` +
+				`model        ${effectiveModel}\n` +
+				`spark base   ${sparkBaseUrl()}\n` +
+				`spark token  ${token ? `${token.slice(0, 12)}... (from ${tokenSource})` : "not required"}\n` +
+				`pi entry     ${piEntry}\n`,
+		);
+		return;
+	}
+
+	if (usesSpark) {
+		const health = await checkEndpoint(sparkBaseUrl(), token);
+		if (!health.ok) {
+			process.stderr.write(
+				`learningcode: warning - Spark at ${sparkBaseUrl()} is not answering (${health.reason}).\n` +
+					"Continuing anyway; check your network or token if the first request fails.\n",
+			);
+		}
+	}
+
+	const child = spawn(process.execPath, [piEntry, ...forced, ...toPi], {
+		stdio: "inherit",
+		env: {
+			...process.env,
+			[PI_AGENT_DIR_ENV]: dir,
+			SPARK_BASE_URL: sparkBaseUrl(),
+			// Unset rather than empty when not on Spark: Pi treats an empty key as
+			// configured for some providers, which would shadow OPENCODE_API_KEY.
+			...(token ? { [TOKEN_ENV]: token } : {}),
+		},
+	});
+
+	// Forward interrupts so Ctrl+C in the terminal reaches Pi rather than
+	// orphaning it behind this wrapper.
+	for (const signal of ["SIGINT", "SIGTERM"]) {
+		process.on(signal, () => child.kill(signal));
+	}
+
+	child.on("error", (error) => fail(`failed to start Pi: ${error.message}`));
+	child.on("exit", (code, signal) => {
+		if (signal) process.kill(process.pid, signal);
+		else process.exit(code ?? 0);
+	});
+}
+
+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/spark-quota.ts

@@ -0,0 +1,113 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Spark-aware status for the learningcode client.
+ *
+ * Spark exposes two endpoints that no stock harness knows about, because they
+ * are not part of the OpenAI API:
+ *
+ *   GET /v1/me/quota  per-student weekly spend, job count, and whether the
+ *                     account is allowed to use AI at all right now
+ *   GET /v1/queue     live seat queue, so a student can see why a turn is waiting
+ *
+ * Both need the same personal token the agent already authenticates with, so we
+ * read it from the environment the launcher sets rather than asking again.
+ */
+
+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 }> {
+	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}` };
+		return { ok: true, body: await response.json() };
+	} catch (error) {
+		return { ok: false, error: error instanceof Error ? error.message : "unreachable" };
+	}
+}
+
+const num = (value: unknown): number => (typeof value === "number" && Number.isFinite(value) ? value : 0);
+
+function quotaLine(body: Record<string, unknown>): string {
+	const used = num(body.tokensUsed);
+	const limit = num(body.dailyTokenLimit);
+	const pct = limit > 0 ? ` (${Math.round((used / limit) * 100)}%)` : "";
+	return [
+		`Spark quota - ${used.toLocaleString()}/${limit.toLocaleString()} tokens${pct}`,
+		`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("  |  ");
+}
+
+/**
+ * The queue view shape is not guaranteed, so surface the fields we recognise
+ * and fall back to raw JSON rather than inventing structure.
+ */
+function queueLine(body: unknown): string {
+	if (!body || typeof body !== "object") return `Spark queue: ${JSON.stringify(body)}`;
+	const record = body as Record<string, unknown>;
+
+	const recognised = ["position", "queued", "waiting", "depth", "active", "seats", "available"];
+	const known = Object.entries(record).filter(([key]) => recognised.includes(key));
+	if (known.length) {
+		return `Spark seats - ${known.map(([k, v]) => `${k} ${JSON.stringify(v)}`).join(", ")}`;
+	}
+	return `Spark seats - ${JSON.stringify(record).slice(0, 200)}`;
+}
+
+export default function sparkQuota(pi: ExtensionAPI) {
+	pi.registerCommand("quota", {
+		description: "Show your Spark token spend for today",
+		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 ? "info" : "warning",
+			);
+		},
+	});
+
+	pi.registerCommand("seats", {
+		description: "Show how many Spark seats are free",
+		handler: async (_args, ctx) => {
+			const result = await call("/queue");
+			ctx.ui.notify(
+				result.ok ? queueLine(result.body) : `seat info unavailable: ${result.error}`,
+				result.ok ? "info" : "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.
+	pi.on("session_start", async (_event, ctx) => {
+		const result = await call("/me/quota");
+		if (!result.ok) return;
+		const body = result.body as Record<string, unknown>;
+
+		if (body.aiEnabled === false) {
+			ctx.ui.notify(
+				"AI is switched off for your Spark account. Ask your teacher, then run /quota.",
+				"warning",
+			);
+			return;
+		}
+
+		const used = num(body.tokensUsed);
+		const limit = num(body.dailyTokenLimit);
+		if (limit > 0 && used / limit >= 0.8) {
+			ctx.ui.notify(
+				`Heads up: ${Math.round((used / limit) * 100)}% of today's Spark quota is gone. Run /quota for detail.`,
+				"warning",
+			);
+		}
+	});
+}

package/lib/config.mjs

@@ -0,0 +1,52 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * An error the user caused or can act on. The launcher prints these as a single
+ * line instead of a stack trace, because a student mistyping a token should not
+ * be shown a JavaScript call stack.
+ */
+export class UserError extends Error {}
+
+/**
+ * Spark exposes exactly one model. These identifiers must match
+ * `inference.model_id` in the spark repo's spark.config.yaml.
+ */
+export const PROVIDER_ID = "tlc-spark";
+export const MODEL_ID = "TLC-Spark";
+
+/** Public Spark deployment. Override with --base-url or LEARNINGCODE_SPARK_BASE_URL. */
+export const DEFAULT_BASE_URL = "https://spark.learning.com.my/v1";
+
+/**
+ * Mirrors the Spark machine profile. `default_context_tokens` is 16384 and
+ * `max_context_tokens` is 32768 in spark.config.yaml; we advertise the ceiling
+ * so Pi's compaction triggers before Spark rejects the request.
+ */
+export const CONTEXT_WINDOW = 32768;
+export const DEFAULT_MAX_OUTPUT_TOKENS = 4096;
+
+/** Env var that makes Pi read its config, models.json and sessions from our agent dir. */
+export const PI_AGENT_DIR_ENV = "PI_CODING_AGENT_DIR";
+
+/** Read by the provider config via `"apiKey": "$SPARK_API_KEY"`. */
+export const TOKEN_ENV = "SPARK_API_KEY";
+
+/** Where the personal `spark_live_` token is cached between runs. */
+export const TOKEN_FILE = "spark-token";
+
+/**
+ * Pi resolves its agent directory from PI_CODING_AGENT_DIR when set, so
+ * learningcode keeps its own config instead of sharing ~/.pi with a stock Pi
+ * install on the same machine.
+ */
+export function agentDir() {
+	const override = process.env.LEARNINGCODE_DIR;
+	if (override) return override.replace(/^~(?=$|\/)/, homedir());
+	return join(homedir(), ".learningcode", "agent");
+}
+
+export function sparkBaseUrl() {
+	const raw = process.env.LEARNINGCODE_SPARK_BASE_URL || DEFAULT_BASE_URL;
+	return raw.replace(/\/+$/, "");
+}

package/lib/models.mjs

@@ -0,0 +1,107 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import {
+	CONTEXT_WINDOW,
+	DEFAULT_MAX_OUTPUT_TOKENS,
+	PROVIDER_ID,
+	MODEL_ID,
+	UserError,
+	sparkBaseUrl,
+} from "./config.mjs";
+
+export function modelsPath(agentDir) {
+	return join(agentDir, "models.json");
+}
+
+/**
+ * The TLC-Spark provider definition.
+ *
+ * Every `compat` flag here is load-bearing. They are not defensive padding --
+ * each one corresponds to a field that Spark's OpenAI-compatible layer either
+ * rejects or silently drops:
+ *
+ *   - `supportsDeveloperRole: false`  Spark's message union is
+ *     `system | user | assistant | tool`. There is no `developer` variant, so a
+ *     reasoning-capable client must send `system` instead or the turn is lost.
+ *   - `maxTokensField: "max_tokens"`  Spark reads `body.max_tokens` only, so
+ *     `max_completion_tokens` would be ignored and the server default used.
+ *   - `supportsReasoningEffort: false`  `reasoning_effort` is not forwarded to
+ *     the runtime, so sending it is a no-op that misleads Pi's level mapping.
+ *   - `supportsStore: false`  `store` is not implemented.
+ *
+ * `reasoning: false` because Spark bills chain-of-thought tokens but never
+ * forwards them to the client (`src/http/v1.ts` drops `chunk.reasoning`), so
+ * Pi would expose thinking controls that can never produce output.
+ */
+export function providerDefinition() {
+	return {
+		name: "TLC Spark",
+		baseUrl: sparkBaseUrl(),
+		api: "openai-completions",
+		// Resolved by Pi from the environment, which the launcher sets from the
+		// cached personal token. Avoids writing the token into a config file.
+		apiKey: "$SPARK_API_KEY",
+		compat: {
+			supportsDeveloperRole: false,
+			supportsReasoningEffort: false,
+			maxTokensField: "max_tokens",
+			supportsStore: false,
+		},
+		models: [
+			{
+				id: MODEL_ID,
+				name: "TLC-Spark (Qwen3.8-27B)",
+				reasoning: false,
+				input: ["text"],
+				contextWindow: CONTEXT_WINDOW,
+				maxTokens: DEFAULT_MAX_OUTPUT_TOKENS,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+			},
+		],
+	};
+}
+
+async function readModels(path) {
+	try {
+		const parsed = JSON.parse(await readFile(path, "utf-8"));
+		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+	} catch (error) {
+		if (error?.code !== "ENOENT") {
+			throw new UserError(
+				`Could not parse ${path}: ${error.message}\nFix or delete the file, then rerun.`,
+			);
+		}
+	}
+	return {};
+}
+
+/**
+ * Ensure `models.json` describes TLC-Spark, without discarding edits a student
+ * may have made. An existing provider entry always wins; we only fill in the
+ * provider when it is absent, so a local experiment survives upgrades.
+ */
+export async function ensureSparkProvider(agentDir) {
+	const path = modelsPath(agentDir);
+	const models = await readModels(path);
+
+	if (models.providers?.[PROVIDER_ID]) return { path, created: false };
+
+	models.providers = { ...models.providers, [PROVIDER_ID]: providerDefinition() };
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, `${JSON.stringify(models, null, 2)}\n`, "utf-8");
+	return { path, created: true };
+}
+
+/**
+ * Point an existing provider entry at a new Spark host. Used when a student
+ * moves between the local bench and the public deployment.
+ */
+export async function retargetProvider(agentDir, baseUrl) {
+	const path = modelsPath(agentDir);
+	const models = await readModels(path);
+	const provider = models.providers?.[PROVIDER_ID];
+	if (!provider) throw new UserError(`${PROVIDER_ID} is not configured in ${path}`);
+	provider.baseUrl = baseUrl.replace(/\/+$/, "");
+	await writeFile(path, `${JSON.stringify(models, null, 2)}\n`, "utf-8");
+	return provider.baseUrl;
+}

package/lib/token.mjs

@@ -0,0 +1,124 @@
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { TOKEN_ENV, TOKEN_FILE, UserError } from "./config.mjs";
+
+const TOKEN_PREFIX = "spark_live_";
+
+export function tokenPath(agentDir) {
+	return join(agentDir, TOKEN_FILE);
+}
+
+async function readCachedToken(agentDir) {
+	try {
+		const value = (await readFile(tokenPath(agentDir), "utf-8")).trim();
+		return value || undefined;
+	} catch (error) {
+		if (error?.code !== "ENOENT") throw error;
+		return undefined;
+	}
+}
+
+async function writeCachedToken(agentDir, token) {
+	const path = tokenPath(agentDir);
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, `${token}\n`, { encoding: "utf-8", mode: 0o600 });
+	// `mode` only applies at creation; tighten it if the file already existed.
+	await chmod(path, 0o600).catch(() => {});
+}
+
+/** Read a secret without echoing it. Falls back to a plain readline if raw mode is unavailable. */
+async function promptSecret(prompt) {
+	const input = process.stdin;
+	const output = process.stdout;
+
+	if (!input.isTTY) {
+		const rl = createInterface({ input, output });
+		const answer = await rl.question(prompt);
+		rl.close();
+		return answer.trim();
+	}
+
+	process.stdout.write(prompt);
+	return new Promise((resolve) => {
+		const stdin = input;
+		stdin.setRawMode(true);
+		stdin.resume();
+		stdin.setEncoding("utf-8");
+		let value = "";
+
+		const onData = (chunk) => {
+			for (const char of chunk) {
+				switch (char) {
+					case "\r":
+					case "\n":
+					case "":
+						stdin.setRawMode(false);
+						stdin.pause();
+						stdin.removeListener("data", onData);
+						process.stdout.write("\n");
+						resolve(value.trim());
+						return;
+					case "":
+						stdin.setRawMode(false);
+						stdin.pause();
+						stdin.removeListener("data", onData);
+						process.stdout.write("\n");
+						resolve(undefined);
+						return;
+					case "":
+					case "\b":
+						if (value.length) {
+							value = value.slice(0, -1);
+							process.stdout.write("\b \b");
+						}
+						break;
+					default:
+						// Ignore control characters, accept printable input.
+						if (char >= " ") {
+							value += char;
+							process.stdout.write("*");
+						}
+				}
+			}
+		};
+
+		stdin.on("data", onData);
+	});
+}
+
+/**
+ * Resolve the personal Spark token, in precedence order:
+ * explicit flag, environment, cached file, interactive prompt.
+ *
+ * Caching matters because a token is issued once and shown only once in the
+ * Spark bench; a student who loses it has to ask for a rotation.
+ */
+export async function resolveToken(agentDir, explicit) {
+	if (explicit) return { token: explicit.trim(), source: "--token" };
+
+	const fromEnv = process.env.LEARNINGCODE_TOKEN || process.env[TOKEN_ENV];
+	if (fromEnv) return { token: fromEnv.trim(), source: "environment" };
+
+	const cached = await readCachedToken(agentDir);
+	if (cached) return { token: cached, source: "cached" };
+
+	const entered = await promptSecret(
+		"Paste your Spark API token (Bench > Issue / rotate token): ",
+	);
+	if (!entered) throw new UserError("No token entered. Run `learningcode --help` for non-interactive setup.");
+	return { token: entered, source: "prompt", shouldCache: true };
+}
+
+export function looksLikeToken(token) {
+	return token.startsWith(TOKEN_PREFIX);
+}
+
+/** True when a token can be found without asking the student anything. */
+export async function hasToken(agentDir, explicit) {
+	if (explicit) return true;
+	if (process.env.LEARNINGCODE_TOKEN || process.env[TOKEN_ENV]) return true;
+	return Boolean(await readCachedToken(agentDir));
+}
+
+export { writeCachedToken };

package/package.json

@@ -0,0 +1,43 @@
+{
+	"name": "@stemtrooper/learningcode",
+	"version": "0.1.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",
+	"bin": {
+		"learningcode": "./bin/learningcode.mjs"
+	},
+	"files": [
+		"bin",
+		"lib",
+		"extensions",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"start": "node ./bin/learningcode.mjs",
+		"test": "node --test \"test/**/*.test.mjs\""
+	},
+	"dependencies": {
+		"@earendil-works/pi-coding-agent": "1.0.4"
+	},
+	"devDependencies": {
+		"jiti": "2.7.0"
+	},
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"keywords": [
+		"coding-agent",
+		"education",
+		"cli",
+		"tui",
+		"tlc",
+		"spark"
+	],
+	"author": "TLC / stemtrooper",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/stemtrooper/learningcode.git"
+	}
+}