From c4b599ec002a6832600d516f61f864be0a1677da Mon Sep 17 00:00:00 2001
From: mptyl <mp@tylconsulting.it>
Date: Sun, 28 Jun 2026 16:04:33 +0200
Subject: [PATCH] feat(backend): ephemeral Pi model lister
 (get_available_models) with TTL cache

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 backend/src/pi/list-models.ts    | 63 ++++++++++++++++++++++++++++++++
 backend/test/list-models.test.ts | 53 +++++++++++++++++++++++++++
 2 files changed, 116 insertions(+)
 create mode 100644 backend/src/pi/list-models.ts
 create mode 100644 backend/test/list-models.test.ts

diff --git a/backend/src/pi/list-models.ts b/backend/src/pi/list-models.ts
new file mode 100644
index 00000000..a7600d0f
--- /dev/null
+++ b/backend/src/pi/list-models.ts
@@ -0,0 +1,63 @@
+import { spawn as nodeSpawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { join } from "node:path";
+import type { AppConfig } from "../config.js";
+import { RpcClient } from "../rpc/rpc-client.js";
+
+export interface PiModel {
+  provider: string;
+  id: string;
+  name: string;
+  reasoning: boolean;
+}
+
+interface Opts {
+  spawnFn?: () => ChildProcessWithoutNullStreams;
+  ttlMs?: number;
+  nowMs?: () => number;
+}
+
+/**
+ * Returns a function that lists Pi's available models (those with auth
+ * configured) via an ephemeral `pi --mode rpc` process. Result is cached for
+ * `ttlMs`. The returned function rejects on timeout/error; callers degrade.
+ */
+export function createPiModelLister(cfg: AppConfig, opts: Opts = {}): () => Promise<PiModel[]> {
+  const ttlMs = opts.ttlMs ?? 60_000;
+  const now = opts.nowMs ?? (() => Date.now());
+  const spawnFn =
+    opts.spawnFn ??
+    (() => {
+      const harnessVenvBin = join(cfg.harnessDir, ".venv", "bin");
+      return nodeSpawn(cfg.piBin, ["--mode", "rpc"], {
+        cwd: cfg.harnessDir,
+        env: { ...process.env, PATH: `${harnessVenvBin}:${process.env.PATH ?? ""}` },
+      }) as ChildProcessWithoutNullStreams;
+    });
+
+  let cache: { at: number; models: PiModel[] } | null = null;
+
+  return async function listModels(): Promise<PiModel[]> {
+    if (cache && now() - cache.at < ttlMs) return cache.models;
+
+    const child = spawnFn();
+    child.stderr.resume();
+    const rpc = new RpcClient(child);
+    try {
+      const resp = await Promise.race([
+        rpc.request({ type: "get_available_models" }),
+        new Promise<never>((_, rej) => setTimeout(() => rej(new Error("pi model list timeout")), 8000)),
+      ]);
+      const raw = (resp?.data?.models ?? []) as Array<Record<string, unknown>>;
+      const models: PiModel[] = raw.map((m) => ({
+        provider: String(m.provider ?? ""),
+        id: String(m.id ?? ""),
+        name: String(m.name ?? m.id ?? ""),
+        reasoning: Boolean(m.reasoning),
+      }));
+      cache = { at: now(), models };
+      return models;
+    } finally {
+      child.kill();
+    }
+  };
+}
diff --git a/backend/test/list-models.test.ts b/backend/test/list-models.test.ts
new file mode 100644
index 00000000..6175cacd
--- /dev/null
+++ b/backend/test/list-models.test.ts
@@ -0,0 +1,53 @@
+import { test, expect } from "vitest";
+import { spawn } from "node:child_process";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import path from "node:path";
+import { createPiModelLister } from "../src/pi/list-models.js";
+import { loadConfig } from "../src/config.js";
+
+const FAKE = path.resolve("../harness/tests/fake_pi/fake_pi_rpc.mjs");
+
+function scriptWith(models: unknown[]): string {
+  const dir = mkdtempSync(join(tmpdir(), "tht-models-"));
+  const file = join(dir, "models.json");
+  writeFileSync(file, JSON.stringify({ available_models: models }));
+  return file;
+}
+
+test("createPiModelLister returns mapped PiModel[] from get_available_models", async () => {
+  const script = scriptWith([
+    { provider: "zai", id: "glm-5.2", name: "GLM 5.2", reasoning: true, extra: "ignored" },
+    { provider: "anthropic", id: "claude-opus-4-8", name: "Claude Opus 4.8", reasoning: true },
+  ]);
+  try {
+    const lister = createPiModelLister(loadConfig({ THT_HARNESS_DIR: "../harness" }), {
+      spawnFn: () => spawn("node", [FAKE, script]) as any,
+    });
+    const models = await lister();
+    expect(models).toEqual([
+      { provider: "zai", id: "glm-5.2", name: "GLM 5.2", reasoning: true },
+      { provider: "anthropic", id: "claude-opus-4-8", name: "Claude Opus 4.8", reasoning: true },
+    ]);
+  } finally {
+    rmSync(path.dirname(script), { recursive: true, force: true });
+  }
+});
+
+test("createPiModelLister caches within ttl (spawns once for two calls)", async () => {
+  const script = scriptWith([{ provider: "zai", id: "glm-5.2", name: "GLM 5.2", reasoning: true }]);
+  try {
+    let spawns = 0;
+    const lister = createPiModelLister(loadConfig({ THT_HARNESS_DIR: "../harness" }), {
+      spawnFn: () => { spawns++; return spawn("node", [FAKE, script]) as any; },
+      ttlMs: 10_000,
+      nowMs: () => 1000,
+    });
+    await lister();
+    await lister();
+    expect(spawns).toBe(1);
+  } finally {
+    rmSync(path.dirname(script), { recursive: true, force: true });
+  }
+});