agent-golf 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent Golf 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.

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# Agent Golf for Pi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pi commands for the Agent Golf coding-agent leaderboard. Login, browsing and submission never call a model or compute scores locally.
+
+**0.1.1:** uses https://agent-golf.csbasics.in and includes read-only interactive problem views. Local integration with the real counter is verified and the production catalogue is reachable. A fresh solved production submission has not been verified; follow your organizer's readiness announcement before competition use.
+
+## Install and update
+
+Requires Node.js 22.19+ and the Pi coding agent (tested with Pi 1.1.0).
+
+```bash
+pi install npm:agent-golf
+```
+
+Unversioned installations follow `latest`. The `preview` channel also receives this URL update; existing preview users can keep that installation source.
+
+Start a new Pi process, or run `/reload` in an existing one. To update an unpinned installation:
+
+```bash
+pi update --extensions
+```
+
+Restart Pi or `/reload` afterward. An exact version such as `npm:agent-golf@0.1.0` is pinned; updating does not advance it to a different version. Remove the old pinned source (`pi remove npm:agent-golf@0.1.0`), then install `npm:agent-golf@0.1.1` explicitly to replace that pin. The `npm:agent-golf@preview` installation follows the preview channel; it does not automatically switch to `latest`.
+
+**Updating from 0.1.0:** the default server origin changed. Unset any old `AGENT_GOLF_API_BASE_URL` override, update/restart Pi, and run `/golf-login` with your student key valid on the new website. Old-origin credentials are preserved but never migrated or sent to the new origin.
+
+## Commands
+
+### `/golf-problems`
+
+Browse public contest rules, challenge URLs, instructions and each problem's model/thinking setup. Rules open first, followed by a problem selector. Close a detail view to return to the list; cancel the list to exit. An empty list still shows the rules.
+
+Interactive Pi uses read-only, scrollable text views: Enter on rules opens the problem list, Esc closes browsing, and Enter/Esc on details returns to the list. Arrow keys, Page Up/Down and Home/End scroll; navigation hints use your configured confirm/cancel keys. RPC clients retain temporary text-editor dialogs with explicit navigation titles; all edits are discarded. Nothing is inserted into your prompt or session. `any` setup is displayed as "any model, one per session" or "any thinking level".
+
+Browsing sends no key, cookie or session log, makes no model calls, and never starts/binds an attempt or changes your setup. The catalogue is advisory; server submission checks are authoritative. Replies are bounded to 64 KB and strings to 1,000 Unicode characters, with terminal-safety and exact Hackattic URL checks.
+
+### `/golf-login <student-key>`
+
+Use the key provided by the Agent Golf website. Validation succeeds before anything is saved. Invalid keys and network/server failures preserve any existing saved credentials.
+
+Credentials are stored separately per server origin in `~/.config/agent-golf/credentials.json`, with directory mode 0700 and file mode 0600. This file contains the original key so the client can authenticate: never share or commit it. Writes are atomic within one Pi process, but are not locked across separate Pi processes. Changing origins never reuses or migrates another server's key.
+
+### `/golf-submit <problem-slug>`
+
+For example:
+
+```text
+/golf-submit help_me_unpack
+```
+
+Submit from the saved session where you solved the problem. Pi must be idle and all user Bash commands must have recorded their results. Confirm the problem, server, byte size and privacy warning before upload; cancelling sends nothing.
+
+**Privacy:** submission uploads the complete unchanged raw JSONL, including abandoned branches. It may contain prompts, local paths, Hackattic access tokens and other sensitive material. Only submit to a server you trust. The website must keep raw logs private; public leaderboard rows should show only permitted identity, metrics and verdicts.
+
+If the session or file changes during confirmation, submission is refused. Folder observations, when known, are sent as informational metadata, not proof that an attempt is eligible. Unknown/forked observations are omitted. User Bash starts are tracked by command hashes outside model context; missing recorded results block submission rather than guessing completion.
+
+The server owns scores and status. A null total with `missing_usage` is displayed as `Tokens: unknown`, never zero. Warnings and model-switch reasons are displayed without client-side reranking.
+
+## Server configuration
+
+Default API origin: **https://agent-golf.csbasics.in**.
+
+For a trusted local server:
+
+```bash
+AGENT_GOLF_API_BASE_URL=http://127.0.0.1:8000 pi
+```
+
+Both authentication and browsing/submission use this origin. Only HTTPS and loopback HTTP are accepted; no credentials, API path, query or fragment belong in the origin. Empty/invalid overrides fail closed and never fall back silently to production. Redirects are refused. Loading the extension alone makes no HTTP requests.
+
+## Troubleshooting
+
+- **No key saved:** run `/golf-login <student-key>` for the configured server.
+- **Invalid key:** retry with your registered key; existing credentials remain unchanged.
+- **Problem list unavailable:** check the configured origin and server availability; the endpoint may not yet be available.
+- **Pi busy or pending Bash:** wait for the response/Bash result to finish recording.
+- **No persisted session file:** submit from the saved attempt, not a fresh custom-only session that has not flushed to disk.
+- **Upload/network error:** the upload may already have reached the server. Check the website before retrying. The plugin never retries automatically.
+
+Removing the package with `pi remove npm:agent-golf` (use the source you installed, e.g. `npm:agent-golf@preview`) does not remove your credential file. Delete that file separately only if you intend to discard saved logins.
+
+## License
+
+MIT for this plugin. This package contains no website/backend implementation or private repository material.

package/config.ts

@@ -0,0 +1,23 @@
+export const DEFAULT_API_ORIGIN = "https://agent-golf.csbasics.in";
+
+export function getApiOrigin(baseUrl: string | undefined): string {
+  if (!baseUrl?.trim()) throw new Error("missing-origin");
+  const url = new URL(baseUrl.trim());
+  const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+  if (
+    url.username || url.password || url.search || url.hash || url.pathname !== "/" ||
+    (url.protocol !== "https:" && !(url.protocol === "http:" && loopback))
+  ) {
+    throw new Error("invalid-origin");
+  }
+  return url.origin;
+}
+
+export function resolveApiOrigin(
+  override?: string,
+  environment: Record<string, string | undefined> = process.env,
+): string {
+  // Only an absent override falls back. An empty/invalid value must not silently
+  // send credentials to production when the user intended another server.
+  return getApiOrigin(override ?? environment.AGENT_GOLF_API_BASE_URL ?? DEFAULT_API_ORIGIN);
+}

package/index.ts

@@ -0,0 +1,160 @@
+import { readdir } from "node:fs/promises";
+import { loginStudent } from "./login.ts";
+import { submitSession } from "./submit.ts";
+import { browseProblems } from "./problems.ts";
+import { USER_BASH_START, userBashStartMetadata } from "./user-bash.ts";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  CustomEntry,
+  SessionEntry,
+  SessionHeader,
+} from "@earendil-works/pi-coding-agent";
+
+export const FOLDER_CHECK_CUSTOM_TYPE = "agent-golf-folder-check";
+export const FOLDER_CHECK_POLICY = "zero-directory-entries";
+
+export type FolderCheckState = "empty" | "nonempty" | "unknown";
+
+export interface FolderCheckMetadata {
+  schema: 1;
+  state: FolderCheckState;
+  checked_at: string;
+  policy: typeof FOLDER_CHECK_POLICY;
+  reason?: string;
+}
+
+interface SessionStartLike {
+  reason: "startup" | "reload" | "new" | "resume" | "fork";
+}
+
+function isFolderCheckMetadata(value: unknown): value is FolderCheckMetadata {
+  if (!value || typeof value !== "object") return false;
+  const data = value as Record<string, unknown>;
+  return (
+    data.schema === 1 &&
+    (data.state === "empty" || data.state === "nonempty" || data.state === "unknown") &&
+    typeof data.checked_at === "string" &&
+    data.policy === FOLDER_CHECK_POLICY &&
+    (data.reason === undefined || typeof data.reason === "string")
+  );
+}
+
+export function getFolderCheckEntries(entries: readonly SessionEntry[]): CustomEntry<FolderCheckMetadata>[] {
+  return entries.filter(
+    (entry): entry is CustomEntry<FolderCheckMetadata> =>
+      entry.type === "custom" &&
+      entry.customType === FOLDER_CHECK_CUSTOM_TYPE &&
+      isFolderCheckMetadata(entry.data),
+  );
+}
+
+export function getInitialFolderCheckMetadata(
+  entries: readonly SessionEntry[],
+): FolderCheckMetadata | undefined {
+  return getFolderCheckEntries(entries)[0]?.data;
+}
+
+export function getFolderWasEmptyUploadValue(
+  header: SessionHeader | null,
+  entries: readonly SessionEntry[],
+): "true" | "false" | undefined {
+  if (header?.parentSession) return undefined;
+
+  const metadata = getInitialFolderCheckMetadata(entries);
+  if (metadata?.state === "empty") return "true";
+  if (metadata?.state === "nonempty") return "false";
+  return undefined;
+}
+
+function observation(state: FolderCheckState, reason?: string): FolderCheckMetadata {
+  return {
+    schema: 1,
+    state,
+    checked_at: new Date().toISOString(),
+    policy: FOLDER_CHECK_POLICY,
+    ...(reason ? { reason } : {}),
+  };
+}
+
+async function observeFreshCwd(cwd: string): Promise<FolderCheckMetadata> {
+  try {
+    const entries = await readdir(cwd);
+    return observation(entries.length === 0 ? "empty" : "nonempty");
+  } catch (error) {
+    const code =
+      error && typeof error === "object" && "code" in error
+        ? String((error as { code?: unknown }).code)
+        : undefined;
+    return observation("unknown", code ? `read-failed:${code}` : "read-failed");
+  }
+}
+
+export async function recordFolderCheckForSession(
+  pi: Pick<ExtensionAPI, "appendEntry">,
+  event: SessionStartLike,
+  ctx: Pick<ExtensionContext, "cwd" | "sessionManager">,
+): Promise<void> {
+  const entries = ctx.sessionManager.getEntries();
+  if (getInitialFolderCheckMetadata(entries)) return;
+
+  const header = ctx.sessionManager.getHeader();
+  let metadata: FolderCheckMetadata;
+
+  if (event.reason === "fork" || header?.parentSession) {
+    metadata = observation("unknown", "inherited-session");
+  } else if (
+    (event.reason === "startup" || event.reason === "new") &&
+    // Startup also fires when the CLI opens an existing session. Only known
+    // initialization entries are safe; all messages (including bash/tool
+    // results), usage, summaries, and unrecognized metadata mean we're too late.
+    entries.every(
+      (entry) =>
+        entry.type === "model_change" ||
+        entry.type === "thinking_level_change" ||
+        entry.type === "session_info",
+    )
+  ) {
+    metadata = await observeFreshCwd(ctx.cwd);
+  } else {
+    metadata = observation("unknown", `not-fresh:${event.reason}`);
+  }
+
+  pi.appendEntry(FOLDER_CHECK_CUSTOM_TYPE, metadata);
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", async (event, ctx) => {
+    await recordFolderCheckForSession(pi, event, ctx);
+  });
+
+  pi.on("user_bash", (event) => {
+    pi.appendEntry(USER_BASH_START, userBashStartMetadata(event.command));
+  });
+
+  pi.registerCommand("golf-login", {
+    description: "Validate and privately save your Agent Golf student key",
+    handler: async (args, ctx) => {
+      const result = await loginStudent(args);
+      ctx.ui.notify(result.message, result.type);
+    },
+  });
+
+  pi.registerCommand("golf-problems", {
+    description: "Browse public Agent Golf rules and problem setup without model calls",
+    handler: async (args, ctx) => {
+      const result = await browseProblems(args, ctx);
+      ctx.ui.notify(result.message, result.type);
+    },
+  });
+
+  pi.registerCommand("golf-submit", {
+    description: "Confirm and upload the current raw session to Agent Golf",
+    handler: async (args, ctx) => {
+      const result = await submitSession(args, ctx, {
+        folderWasEmpty: getFolderWasEmptyUploadValue(ctx.sessionManager.getHeader(), ctx.sessionManager.getEntries()),
+      });
+      ctx.ui.notify(result.message, result.type);
+    },
+  });
+}

package/login.ts

@@ -0,0 +1,161 @@
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, rename, unlink } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { getApiOrigin, resolveApiOrigin } from "./config.ts";
+export { getApiOrigin } from "./config.ts";
+
+export interface LoginOptions {
+  baseUrl?: string;
+  credentialDir?: string;
+  timeoutMs?: number;
+}
+
+export interface LoginResult {
+  message: string;
+  type: "info" | "error";
+}
+
+interface Credential {
+  key: string;
+  username: string;
+}
+
+interface CredentialFile {
+  schema: 1;
+  credentials: Record<string, Credential>;
+}
+
+const USERNAME = /^[a-z0-9_]{3,32}$/;
+const SETUP_MESSAGE = "Set AGENT_GOLF_API_BASE_URL to the server origin (for local testing: http://localhost:8000).";
+
+function isCredentialFile(value: unknown): value is CredentialFile {
+  if (!value || typeof value !== "object") return false;
+  const data = value as Partial<CredentialFile>;
+  if (data.schema !== 1 || !data.credentials || typeof data.credentials !== "object" || Array.isArray(data.credentials)) return false;
+  return Object.entries(data.credentials).every(([origin, credential]) => {
+    try {
+      return getApiOrigin(origin) === origin && !!credential &&
+        typeof credential.key === "string" && credential.key.length > 0 &&
+        typeof credential.username === "string" && USERNAME.test(credential.username);
+    } catch {
+      return false;
+    }
+  });
+}
+
+export async function readStoredCredential(
+  origin: string,
+  directory = join(homedir(), ".config", "agent-golf"),
+): Promise<Credential | undefined> {
+  let file;
+  try {
+    const folder = await lstat(directory);
+    if (!folder.isDirectory() || (folder.mode & 0o077) !== 0) throw new Error("insecure-credential-directory");
+    file = await open(join(directory, "credentials.json"), constants.O_RDONLY | constants.O_NOFOLLOW);
+    const info = await file.stat();
+    if (!info.isFile() || (info.mode & 0o077) !== 0) throw new Error("insecure-credential-file");
+    const parsed: unknown = JSON.parse(await file.readFile("utf8"));
+    if (!isCredentialFile(parsed)) throw new Error("invalid-credential-file");
+    return parsed.credentials[origin];
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return undefined;
+    throw error;
+  } finally {
+    await file?.close();
+  }
+}
+
+// Serialize read-modify-write operations within this Pi process so concurrent
+// logins to different origins don't erase one another's saved credentials.
+let pendingSave: Promise<void> = Promise.resolve();
+
+async function writeCredential(origin: string, key: string, username: string, directory: string): Promise<void> {
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  if (!(await lstat(directory)).isDirectory()) throw new Error("invalid-credential-directory");
+  await chmod(directory, 0o700);
+  const destination = join(directory, "credentials.json");
+  let data: CredentialFile = { schema: 1, credentials: {} };
+  let existing;
+  try {
+    existing = await open(destination, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const parsed: unknown = JSON.parse(await existing.readFile("utf8"));
+    if (!isCredentialFile(parsed)) throw new Error("invalid-credential-file");
+    data = parsed;
+  } catch (error) {
+    if (!(error && typeof error === "object" && "code" in error && error.code === "ENOENT")) throw error;
+  } finally {
+    await existing?.close();
+  }
+  data.credentials[origin] = { key, username };
+
+  const temporary = join(directory, `.credentials-${randomUUID()}.tmp`);
+  const file = await open(temporary, "wx", 0o600);
+  try {
+    try {
+      await file.chmod(0o600);
+      await file.writeFile(JSON.stringify(data) + "\n", "utf8");
+      await file.sync();
+    } finally {
+      await file.close();
+    }
+    await rename(temporary, destination);
+  } finally {
+    await unlink(temporary).catch(() => {});
+  }
+}
+
+export async function loginStudent(args: string, options: LoginOptions = {}): Promise<LoginResult> {
+  const key = args.trim();
+  if (!key || /\s|[\x00-\x1f\x7f]/.test(key)) {
+    return { message: "Usage: /golf-login <key>", type: "info" };
+  }
+
+  let origin: string;
+  try {
+    origin = resolveApiOrigin(options.baseUrl);
+  } catch {
+    return { message: `Invalid server origin override. ${SETUP_MESSAGE} Use HTTPS except for loopback development; do not include credentials, a path, query, or fragment.`, type: "error" };
+  }
+
+  let username: string;
+  try {
+    const response = await fetch(`${origin}/api/v1/me`, {
+      headers: { Authorization: `Bearer ${key}`, Accept: "application/json" },
+      redirect: "error",
+      signal: AbortSignal.timeout(options.timeoutMs ?? 10_000),
+    });
+    if (response.status === 401) {
+      await response.body?.cancel();
+      return { message: "Invalid student key. Run /golf-login <key> with your registered key. Existing credentials were not changed.", type: "error" };
+    }
+    if (response.status !== 200) {
+      await response.body?.cancel();
+      return { message: "The server could not validate the key. Existing credentials were not changed.", type: "error" };
+    }
+    if (!/^application\/json(?:\s*;|$)/i.test(response.headers.get("content-type") ?? "")) {
+      await response.body?.cancel();
+      return { message: "Invalid login response from the server. Existing credentials were not changed.", type: "error" };
+    }
+    const data: unknown = await response.json();
+    if (!data || typeof data !== "object" || !("username" in data) || typeof data.username !== "string" || !USERNAME.test(data.username)) {
+      return { message: "Invalid login response from the server. Existing credentials were not changed.", type: "error" };
+    }
+    username = data.username;
+  } catch {
+    // Never display server bodies or exception strings: either can contain keys.
+    return { message: "Login failed: server unreachable, request timed out, redirect refused, or invalid response. Check the configured server address and connection, then retry /golf-login. Existing credentials were not changed.", type: "error" };
+  }
+
+  try {
+    const save = pendingSave.then(() => writeCredential(
+      origin, key, username, options.credentialDir ?? join(homedir(), ".config", "agent-golf"),
+    ));
+    pendingSave = save.catch(() => {});
+    await save;
+  } catch {
+    return { message: "Key validated, but credentials could not be saved securely. Existing credentials were not replaced.", type: "error" };
+  }
+  return { message: `Logged in as ${username} on ${origin}.`, type: "info" };
+}

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "agent-golf",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Zero-model-call Pi commands for Agent Golf login, raw session submission and problem browsing",
+  "license": "MIT",
+  "homepage": "https://agent-golf.csbasics.in",
+  "keywords": ["pi-package", "agent-golf"],
+  "engines": { "node": ">=22.19.0" },
+  "files": ["index.ts", "config.ts", "login.ts", "submit.ts", "user-bash.ts", "problems.ts", "problem-view.ts", "README.md", "LICENSE"],
+  "pi": { "extensions": ["./index.ts"], "skills": [], "prompts": [], "themes": [] },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "type": "module",
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {}
+}

package/problem-view.ts

@@ -0,0 +1,74 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+type TuiModule = typeof import("@earendil-works/pi-tui");
+type Factory = Parameters<ExtensionContext["ui"]["custom"]>[0];
+type Tui = Parameters<Factory>[0];
+type Theme = Parameters<Factory>[1];
+type Bindings = Parameters<Factory>[2];
+
+// Dependency injection keeps rendering tests independent of Pi's module loader.
+export function createProblemView(
+  lib: TuiModule, tui: Tui, theme: Theme, bindings: Bindings,
+  done: (continued: boolean) => void, title: string, body: string, action: string, cancel: string,
+) {
+  const text = new lib.Text(body, 0, 0);
+  const scroll = new lib.ScrollView(text, { scrollbar: "hidden", overscroll: "contain" });
+  let height = 1;
+  let closed = false;
+  const finish = (value: boolean) => { if (!closed) { closed = true; done(value); } };
+  const keys = (name: "tui.select.confirm" | "tui.select.cancel") => bindings.getKeys(name).join("/");
+  return {
+    render(width: number) {
+      const w = Math.max(1, Math.floor(width));
+      const confirmKey = keys("tui.select.confirm"), cancelKey = keys("tui.select.cancel");
+      const navigation = action === cancel ? `${confirmKey}/${cancelKey}: ${action}` :
+        `${confirmKey}: ${action} · ${cancelKey}: ${cancel}`;
+      const navigationLines = new lib.Text(navigation, 0, 0).render(w);
+      const available = Math.max(1, tui.terminal.rows - 5);
+      // Physically tiny terminals cannot fit body plus controls; ask for resize
+      // rather than presenting a clipped action as if it were the full help.
+      if (w < 12 || navigationLines.length + 2 > available) {
+        return [lib.truncateToWidth("Resize terminal", w),
+          ...new lib.Text(`${confirmKey}/${cancelKey}`, 0, 0).render(w)].slice(0, available);
+      }
+      const showScrollHint = available >= navigationLines.length + 3;
+      height = Math.max(1, Math.min(16, available - 1 - navigationLines.length - Number(showScrollHint)));
+      const lines = text.render(w);
+      scroll.updateLayout(lines.length, height, () => tui.requestRender());
+      const visible = lines.slice(scroll.scrollTop, scroll.scrollTop + height);
+      const scrollHint = `${w < 45 ? "↑/↓ scroll" : "↑/↓ PgUp/PgDn Home/End: scroll"} · ${scroll.scrollTop + 1}-${Math.min(lines.length, scroll.scrollTop + height)}/${lines.length}`;
+      return [
+        lib.truncateToWidth(theme.fg("accent", title), w),
+        ...visible,
+        ...navigationLines.map((line) => theme.fg("muted", line)),
+        ...(showScrollHint ? [lib.truncateToWidth(theme.fg("muted", scrollHint), w)] : []),
+      ];
+    },
+    handleInput(data: string) {
+      if (closed) return;
+      if (bindings.matches(data, "tui.select.cancel") || lib.matchesKey(data, lib.Key.ctrl("c"))) { finish(false); return; }
+      if (bindings.matches(data, "tui.select.confirm")) { finish(true); return; }
+      if (lib.matchesKey(data, lib.Key.up)) scroll.scrollBy(-1);
+      else if (lib.matchesKey(data, lib.Key.down)) scroll.scrollBy(1);
+      else if (lib.matchesKey(data, lib.Key.pageUp)) scroll.scrollBy(-height);
+      else if (lib.matchesKey(data, lib.Key.pageDown)) scroll.scrollBy(height);
+      else if (lib.matchesKey(data, lib.Key.home)) scroll.scrollToStart();
+      else if (lib.matchesKey(data, lib.Key.end)) scroll.scrollToEnd();
+      // No input/editor exists: typing and paste cannot alter the displayed text.
+    },
+    invalidate() { text.invalidate(); scroll.invalidate(); },
+  };
+}
+
+export async function showProblemView(
+  ctx: Pick<ExtensionContext, "ui" | "mode">,
+  title: string, body: string, action: string, cancel: string,
+): Promise<boolean> {
+  if (ctx.mode !== "tui") {
+    return await ctx.ui.editor(`${title} — Enter: ${action}; Esc: ${cancel} (not an upload)`,
+      `${body}\n\nViewer only. Enter navigates; it does not upload. Edits are discarded.`) !== undefined;
+  }
+  const lib = await import("@earendil-works/pi-tui");
+  return ctx.ui.custom<boolean>((tui, theme, bindings, done) =>
+    createProblemView(lib, tui, theme, bindings, done, title, body, action, cancel));
+}

package/problems.ts

@@ -0,0 +1,122 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { resolveApiOrigin } from "./config.ts";
+import { showProblemView } from "./problem-view.ts";
+
+export const MAX_PROBLEM_BODY_BYTES = 64 * 1024;
+const MAX_STRING_CHARACTERS = 1000;
+const UNAVAILABLE = "Problem list unavailable. Check the configured server and connection, then try /golf-problems again.";
+const ADVISORY = "Informational only: browsing does not start or bind an attempt. Upload checks remain authoritative. Nothing is uploaded by browsing.";
+
+interface Problem {
+  slug: string;
+  title: string;
+  challenge_url: string;
+  instructions: string[];
+  model: string;
+  thinking_level: string;
+}
+interface Catalogue { rules_version: string; rules: string[]; problems: Problem[] }
+interface Result { message: string; type: "info" | "error" }
+export interface ProblemOptions { baseUrl?: string; timeoutMs?: number }
+
+function safeStrings(value: unknown): boolean {
+  if (typeof value === "string") {
+    // Newlines/tabs are ordinary text in the temporary editor, not escapes.
+    return Array.from(value).length <= MAX_STRING_CHARACTERS && value.isWellFormed() &&
+      !/[\x00-\x08\x0b-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/u.test(value);
+  }
+  if (Array.isArray(value)) return value.every(safeStrings);
+  if (value && typeof value === "object") return Object.entries(value).every(([key, item]) => safeStrings(key) && safeStrings(item));
+  return true;
+}
+
+function catalogue(value: unknown): Catalogue | undefined {
+  if (!value || typeof value !== "object" || !safeStrings(value)) return undefined;
+  const data = value as Record<string, unknown>;
+  const text = (item: unknown): item is string => typeof item === "string" && item.trim().length > 0;
+  const texts = (item: unknown): item is string[] => Array.isArray(item) && item.every((s) => typeof s === "string");
+  if (!text(data.rules_version) || !texts(data.rules) || !Array.isArray(data.problems)) return undefined;
+  const slugs = new Set<string>();
+  for (const item of data.problems) {
+    if (!item || typeof item !== "object") return undefined;
+    const problem = item as Record<string, unknown>;
+    if (!text(problem.slug) || !/^[a-z0-9]+(?:_[a-z0-9]+)*$/.test(problem.slug) || slugs.has(problem.slug) ||
+      !text(problem.title) || problem.challenge_url !== `https://hackattic.com/challenges/${problem.slug}` ||
+      !texts(problem.instructions) || !text(problem.model) || !text(problem.thinking_level)) return undefined;
+    if (problem.model !== "any" && !/^[^\s/]+\/\S+$/.test(problem.model)) return undefined;
+    if (!/^[a-z][a-z0-9_-]*$/.test(problem.thinking_level)) return undefined;
+    slugs.add(problem.slug);
+  }
+  return data as unknown as Catalogue;
+}
+
+async function readCatalogue(response: Response): Promise<Catalogue | undefined> {
+  if (!response.body) return undefined;
+  const reader = response.body.getReader();
+  let size = 0;
+  const chunks: Uint8Array[] = [];
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > MAX_PROBLEM_BODY_BYTES) return undefined;
+      chunks.push(value);
+    }
+    return catalogue(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks))));
+  } finally {
+    await reader.cancel();
+    reader.releaseLock();
+  }
+}
+
+let browsing = false;
+export async function browseProblems(
+  args: string,
+  ctx: Pick<ExtensionContext, "ui" | "hasUI" | "mode">,
+  options: ProblemOptions = {},
+): Promise<Result> {
+  if (args.trim()) return { message: "Usage: /golf-problems", type: "info" };
+  if (!ctx.hasUI) return { message: "Problem browsing requires interactive Pi or an RPC client with UI support.", type: "error" };
+  if (browsing) return { message: "Another problem browser is open. Close it first.", type: "error" };
+  browsing = true;
+  try {
+    const origin = resolveApiOrigin(options.baseUrl);
+    const response = await fetch(`${origin}/api/v1/problems`, {
+      headers: { Accept: "application/json" }, credentials: "omit", redirect: "error",
+      signal: AbortSignal.timeout(options.timeoutMs ?? 10_000),
+    });
+    if (response.status !== 200 || !/^application\/json(?:\s*;|$)/i.test(response.headers.get("content-type") ?? "") ||
+      Number(response.headers.get("content-length")) > MAX_PROBLEM_BODY_BYTES) {
+      await response.body?.cancel();
+      return { message: UNAVAILABLE, type: "error" };
+    }
+    const data = await readCatalogue(response);
+    if (!data) return { message: UNAVAILABLE, type: "error" };
+    const rules = [`Rules version: ${data.rules_version}`, "", ...data.rules, "", ADVISORY];
+    if (!data.problems.length) rules.push("", "No problems are currently listed.");
+    const continued = await showProblemView(ctx, "Agent Golf rules", rules.join("\n"),
+      data.problems.length ? "view problems" : "close", "close");
+    if (continued && data.problems.length) {
+      const labels = data.problems.map((p) => `${p.title.replace(/[\n\t]/g, " ")} (${p.slug})`);
+      while (true) {
+        const selected = await ctx.ui.select("Agent Golf problems — choose to view details", labels);
+        const index = selected === undefined ? -1 : labels.indexOf(selected);
+        if (index < 0) break;
+        const problem = data.problems[index];
+        await showProblemView(ctx, "Problem details", [
+          problem.title, `Problem: ${problem.slug}`, problem.challenge_url,
+          `Model: ${problem.model === "any" ? "any model, one per session" : problem.model}`,
+          `Thinking level: ${problem.thinking_level === "any" ? "any thinking level" : problem.thinking_level}`,
+          "", ...problem.instructions, "", ADVISORY,
+        ].join("\n"), "back to problems", "back to problems");
+      }
+    }
+    return { message: "Problem browsing closed. No attempt or setup was changed.", type: "info" };
+  } catch {
+    // Never render arbitrary error bodies, URL overrides or exception strings.
+    return { message: UNAVAILABLE, type: "error" };
+  } finally {
+    browsing = false;
+  }
+}

package/submit.ts

@@ -0,0 +1,147 @@
+import { readFile } from "node:fs/promises";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { readStoredCredential, type LoginResult } from "./login.ts";
+import { getApiOrigin, resolveApiOrigin } from "./config.ts";
+import { hasPendingUserBash } from "./user-bash.ts";
+
+export interface SubmitOptions {
+  baseUrl?: string;
+  credentialDir?: string;
+  timeoutMs?: number;
+  folderWasEmpty?: "true" | "false";
+}
+
+type SubmitContext = Pick<ExtensionContext, "ui" | "hasUI" | "isIdle" | "sessionManager">;
+
+const REASONS = new Set([
+  "not_solved", "model_mismatch", "thinking_level_mismatch", "model_switched", "folder_reused", "missing_usage",
+  "custom_setup", "inconsistent_log", "usage_not_recorded", "bad_key", "not_pi_log", "unknown_problem", "file_too_large",
+]);
+
+function error(message: string): LoginResult {
+  return { message, type: "error" };
+}
+
+function formatReply(value: unknown, httpStatus: number, key: string): LoginResult | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const data = value as Record<string, unknown>;
+  if (!Array.isArray(data.reasons) || !data.reasons.every((reason) => typeof reason === "string" && REASONS.has(reason))) return undefined;
+  const reasons = data.reasons.length ? data.reasons.join(", ") : "none";
+  if (httpStatus !== 200) {
+    if (data.status !== "rejected" || data.metrics !== null || data.url !== null) return undefined;
+    const allowed = httpStatus === 401 ? ["bad_key"] : httpStatus === 413 ? ["file_too_large"] : ["not_pi_log", "unknown_problem"];
+    if (!data.reasons.length || !data.reasons.every((reason) => allowed.includes(reason))) return undefined;
+    return error(`Submission rejected: ${reasons}.${httpStatus === 401 ? " Run /golf-login with a valid key for this server." : ""}`);
+  }
+  if (data.status !== "ranked" && data.status !== "unranked") return undefined;
+  if (!data.metrics || typeof data.metrics !== "object" || typeof data.url !== "string") return undefined;
+  const metrics = data.metrics as Record<string, unknown>;
+  const unknownTokens = data.reasons.includes("missing_usage");
+  // Validate the contract's null/reason pair, not the score or ranking verdict.
+  if (unknownTokens !== (metrics.total_tokens === null)) return undefined;
+  for (const name of ["total_tokens", "prompts", "chars_typed", "tool_calls"]) {
+    if (name === "total_tokens" && unknownTokens) continue;
+    if (typeof metrics[name] !== "number" || !Number.isSafeInteger(metrics[name]) || metrics[name] < 0) return undefined;
+  }
+  for (const name of ["models", "thinking_levels"]) {
+    if (!Array.isArray(metrics[name]) || !metrics[name].every((item) => typeof item === "string" && !/[\x00-\x1f\x7f]/.test(item))) return undefined;
+  }
+  if (typeof metrics.solved !== "boolean") return undefined;
+  let url: URL;
+  try {
+    url = new URL(data.url);
+    getApiOrigin(url.origin);
+    if (url.username || url.password || /[\x00-\x1f\x7f]/.test(data.url)) return undefined;
+  } catch {
+    return undefined;
+  }
+  const message = [
+    `Submission ${data.status}. Reasons: ${reasons}.`,
+    `Tokens: ${unknownTokens ? "unknown" : metrics.total_tokens}; prompts: ${metrics.prompts}; characters: ${metrics.chars_typed}; tool calls: ${metrics.tool_calls}; solved: ${metrics.solved}.`,
+    `Models: ${(metrics.models as string[]).join(", ")}; thinking levels: ${(metrics.thinking_levels as string[]).join(", ")}.`,
+    url.href,
+  ].join("\n");
+  if (message.includes(key)) return undefined;
+  return { message, type: "info" };
+}
+
+// One upload at a time within this extension runtime; no model interaction.
+let submitting = false;
+
+export async function submitSession(args: string, ctx: SubmitContext, options: SubmitOptions = {}): Promise<LoginResult> {
+  const problem = args.trim();
+  if (!/^[a-z0-9]+(?:_[a-z0-9]+)*$/.test(problem)) return { message: "Usage: /golf-submit <problem> (for example: help_me_unpack)", type: "info" };
+  if (submitting) return error("Another submission is already in progress. Wait for it to finish.");
+  submitting = true;
+  try {
+    if (!ctx.hasUI) return error("Submission requires a confirmation dialog. Use interactive Pi or an RPC client with UI support.");
+    if (!ctx.isIdle()) return error("Pi is busy. Finish the current response before submitting.");
+    if (hasPendingUserBash(ctx.sessionManager.getEntries())) return error("A user Bash command is still running or its result has not been recorded. Wait for it to finish before submitting.");
+    let origin: string;
+    try {
+      origin = resolveApiOrigin(options.baseUrl);
+    } catch {
+      return error("Invalid server origin override. Set AGENT_GOLF_API_BASE_URL to a valid HTTPS server origin (loopback HTTP is allowed for local testing).");
+    }
+    let credential;
+    try {
+      credential = await readStoredCredential(origin, options.credentialDir);
+    } catch {
+      return error("Stored credentials could not be read securely. Run /golf-login again; check the private credential file if the problem persists.");
+    }
+    if (!credential) return error("No key saved for this server. Run /golf-login <key> first.");
+
+    const sessionId = ctx.sessionManager.getSessionId();
+    const sessionFile = ctx.sessionManager.getSessionFile();
+    const leafId = ctx.sessionManager.getLeafId();
+    if (!sessionFile) return error("No persisted session file is available. Submit from the saved session where you solved the problem.");
+    let bytes: Buffer;
+    try {
+      bytes = await readFile(sessionFile);
+    } catch {
+      return error("The current session file is unavailable or unreadable. Nothing was uploaded.");
+    }
+    if (!bytes.length) return error("The current session file is empty. Nothing was uploaded.");
+    const stillCurrent = () => ctx.isIdle() && !hasPendingUserBash(ctx.sessionManager.getEntries()) && ctx.sessionManager.getSessionId() === sessionId &&
+      ctx.sessionManager.getSessionFile() === sessionFile && ctx.sessionManager.getLeafId() === leafId;
+    if (!stillCurrent()) return error("Pi or the session changed while preparing submission. Try again when idle.");
+    const confirmed = await ctx.ui.confirm("Submit to Agent Golf?", [
+      `Problem: ${problem}`,
+      `Server: ${origin}`,
+      `Session file size: ${bytes.length} bytes`,
+      "This uploads the complete raw session, including abandoned branches. It may contain Hackattic tokens, prompts, and local paths. Only proceed if you trust this server.",
+    ].join("\n"));
+    if (!confirmed) return { message: "Submission cancelled. Nothing was uploaded.", type: "info" };
+    if (!stillCurrent()) return error("Pi or the session changed during confirmation. Nothing was uploaded; try again when idle.");
+    const currentBytes = await readFile(sessionFile);
+    if (!bytes.equals(currentBytes) || !stillCurrent()) return error("The session changed during confirmation. Nothing was uploaded; try again.");
+
+    const form = new FormData();
+    form.append("problem", problem);
+    form.append("session", new Blob([new Uint8Array(bytes)], { type: "application/x-ndjson" }), "session.jsonl");
+    if (options.folderWasEmpty !== undefined) form.append("folder_was_empty", options.folderWasEmpty);
+    try {
+      const response = await fetch(`${origin}/api/v1/submissions`, {
+        method: "POST", headers: { Authorization: `Bearer ${credential.key}`, Accept: "application/json" },
+        body: form, redirect: "error", signal: AbortSignal.timeout(options.timeoutMs ?? 60_000),
+      });
+      if (![200, 400, 401, 413].includes(response.status)) {
+        await response.body?.cancel();
+        return error("Submission failed: server error. This does not mean your file or key is invalid.");
+      }
+      if (!/^application\/json(?:\s*;|$)/i.test(response.headers.get("content-type") ?? "")) {
+        await response.body?.cancel();
+        return error("The server returned an invalid submission response. Check the website before retrying.");
+      }
+      const result = formatReply(await response.json(), response.status, credential.key);
+      return result ?? error("The server returned an invalid submission response. Check the website before retrying.");
+    } catch {
+      // Never display exceptions or arbitrary response bodies: they may contain keys/logs.
+      return error("Submission failed: server unreachable, request timed out, redirect refused, or invalid response. The upload may have reached the server; check the website before retrying.");
+    }
+  } catch {
+    return error("Submission stopped because the session or local file became unavailable. No automatic retry was made.");
+  } finally {
+    submitting = false;
+  }
+}

package/user-bash.ts

@@ -0,0 +1,28 @@
+import { createHash } from "node:crypto";
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+
+export const USER_BASH_START = "agent-golf-user-bash-start";
+
+export function userBashStartMetadata(command: string) {
+  return { schema: 1, command_sha256: createHash("sha256").update(command).digest("hex") };
+}
+
+// user_bash fires before execution; the Bash result is appended only after it
+// finishes (or after deferred results are flushed). Scan the whole session,
+// not just the active branch, to match starts with their recorded results.
+// Custom markers persist across reloads and never enter model context.
+export function hasPendingUserBash(entries: readonly SessionEntry[]): boolean {
+  const pending = new Map<string, number>();
+  for (const entry of entries) {
+    if (entry.type === "custom" && entry.customType === USER_BASH_START) {
+      const data = entry.data as { schema?: unknown; command_sha256?: unknown } | null;
+      if (!data || data.schema !== 1 || typeof data.command_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(data.command_sha256)) return true;
+      pending.set(data.command_sha256, (pending.get(data.command_sha256) ?? 0) + 1);
+    } else if (entry.type === "message" && entry.message.role === "bashExecution") {
+      const digest = userBashStartMetadata(entry.message.command).command_sha256;
+      const count = pending.get(digest) ?? 0;
+      if (count > 0) pending.set(digest, count - 1);
+    }
+  }
+  return [...pending.values()].some((count) => count > 0);
+}