@spunto/build 0.3.0 → 0.4.0

package/src/agent-stream/model-window.ts

@@ -0,0 +1,189 @@
+/**
+ * How big a session's context window is.
+ *
+ * Split out of `agent-stream.ts` because this is not a fact about a dialect. Which harness wrote
+ * the numbers is that file's problem; "how full is this window" outlives the harness, and it has
+ * two answers of very different quality:
+ *
+ *  1. **The catalogue below** — a table, and therefore already wrong on the day a model ships.
+ *     It costs nothing: no credential, no network, no latency. It is the floor, not the answer.
+ *  2. **The Models API** — `GET /v1/models/{id}` → `max_input_tokens`, the model's own answer
+ *     about itself. Used whenever the task's secrets carry an Anthropic credential of either
+ *     kind (`ANTHROPIC_API_KEY`, or a subscription token — see `ModelCredential`), which is
+ *     exactly where a session's credentials already live, and memoised per process because a
+ *     model's window does not move.
+ *
+ * Neither of them guesses. A model in neither source is worth `null`, and the panel then shows a
+ * token count with no percentage — the rule this file inherits from the meter it feeds: a
+ * percentage against a window we invented is worse than no percentage, because the token count
+ * is still true and a wrong bar is not.
+ *
+ * **Why the catalogue is not a pattern match.** It used to be one — `/claude|opus|sonnet|haiku/`
+ * → 200K, with the `[1m]` suffix as the only way to reach 1M. That reads as a safe default and
+ * is not one: every current Claude model except Haiku 4.5 carries a 1M window, so the regex
+ * answered 200K for a session with five times that room, and the meter pegged at 100% somewhere
+ * around a fifth of the way in. Worse, the escape hatch never fired: `[1m]` is how Claude Code
+ * spells the *opt-in* to a long window, and a model whose 1M is native (Opus 5 and the whole
+ * 4.6-and-later line — 1M is both its default and its maximum) is spelled plainly. Measured from
+ * a real `system/init` line: `"model":"claude-opus-5"`, no suffix, 1M of room, 200K on the bar.
+ *
+ * So: exact ids, `null` for anything else, and a live lookup for the cases a table cannot cover.
+ */
+
+/** A Claude Code session opened on the long-context *variant* of its model — `claude-opus-5[1m]`. */
+const LONG_CONTEXT_SUFFIX = "[1m]"
+
+/**
+ * Windows by exact API id, in tokens.
+ *
+ * Exact, because a family prefix is precisely how the previous guess went wrong. A model missing
+ * from here is not assumed into a neighbour's window — it gets `null` and the Models API is asked
+ * instead. That is the property worth keeping as models keep shipping: the next generation reads
+ * as unknown, never as 200K.
+ */
+const WINDOWS: Record<string, number> = {
+  // 1M native — no opt-in, no suffix, nothing to detect in the stream.
+  "claude-fable-5-1": 1_000_000,
+  "claude-fable-5": 1_000_000,
+  "claude-mythos-5-1": 1_000_000,
+  "claude-mythos-5": 1_000_000,
+  "claude-mythos-preview": 1_000_000,
+  "claude-opus-5": 1_000_000,
+  "claude-opus-4-8": 1_000_000,
+  "claude-opus-4-7": 1_000_000,
+  "claude-opus-4-6": 1_000_000,
+  "claude-sonnet-5": 1_000_000,
+  "claude-sonnet-4-6": 1_000_000,
+  // 200K — the generation the old default was written against, plus Haiku, which stayed there.
+  "claude-haiku-4-5": 200_000,
+  "claude-opus-4-5": 200_000,
+  "claude-opus-4-1": 200_000,
+  "claude-opus-4-0": 200_000,
+  "claude-opus-4": 200_000,
+  "claude-sonnet-4-5": 200_000,
+  "claude-sonnet-4-0": 200_000,
+  "claude-sonnet-4": 200_000,
+  "claude-3-7-sonnet": 200_000,
+  "claude-3-5-sonnet": 200_000,
+  "claude-3-5-haiku": 200_000,
+  "claude-3-haiku": 200_000,
+  "claude-3-opus": 200_000,
+}
+
+/**
+ * The API id inside whatever a harness wrote, so one catalogue covers every spelling of a model.
+ *
+ * Claude Code adds `[1m]`, Bedrock prefixes `anthropic.` (sometimes behind a region), Vertex
+ * separates the snapshot with `@`, and a pinned id carries a trailing date. None of that changes
+ * which model ran.
+ */
+export function apiModelId(model: string): string {
+  return model
+    .trim()
+    .toLowerCase()
+    .replaceAll(LONG_CONTEXT_SUFFIX, "")
+    .replace(/^(?:[a-z]{2}\.)?anthropic\./, "")
+    .replace(/@.*$/, "")
+    .replace(/-v\d+:\d+$/, "")
+    .replace(/-\d{8}$/, "")
+    .trim()
+}
+
+/**
+ * The window a model string implies, from the catalogue alone — no credential, no network.
+ *
+ * `null` for anything unrecognised, which now includes any model newer than this table: see the
+ * header. Kept as the synchronous fallback for `summarizeUsage`, which reduces events that were
+ * stored before any of this existed.
+ */
+export function contextWindowOf(model: string | null | undefined): number | null {
+  if (typeof model !== "string" || !model) return null
+  if (model.includes(LONG_CONTEXT_SUFFIX)) return 1_000_000
+  return WINDOWS[apiModelId(model)] ?? null
+}
+
+const MODELS_ENDPOINT = "https://api.anthropic.com/v1/models"
+/** A read path polled every two seconds waits for nothing; the catalogue answers if this does not. */
+const LOOKUP_TIMEOUT_MS = 4_000
+/** A window is immutable, so a hit is kept for the life of the process. A miss is retried later. */
+const MISS_TTL_MS = 10 * 60_000
+
+const memo = new Map<string, { window: number | null; at: number }>()
+
+/** Only for tests — the memo is process-wide on purpose. */
+export function resetModelWindowCache(): void {
+  memo.clear()
+}
+
+/**
+ * How a task's session authenticates against Anthropic, because the two kinds do not use the
+ * same header and sending both at once is rejected outright.
+ *
+ *  - `api-key` — `ANTHROPIC_API_KEY`, on `x-api-key`.
+ *  - `oauth` — a subscription credential (`CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_AUTH_TOKEN`), on
+ *    `Authorization: Bearer` **plus** the `oauth-2025-04-20` beta header. Converting one to the
+ *    other is a header change, not a value swap, which is exactly why this is a tagged union and
+ *    not a string: a token sent as `x-api-key` fails, quietly, as a 401 that looks like a
+ *    revoked key.
+ */
+export type ModelCredential = { kind: "api-key" | "oauth"; value: string }
+
+function authHeaders(credential: ModelCredential): Record<string, string> {
+  return credential.kind === "oauth"
+    ? { authorization: `Bearer ${credential.value}`, "anthropic-beta": "oauth-2025-04-20" }
+    : { "x-api-key": credential.value }
+}
+
+/**
+ * Ask the Models API what the model's window is.
+ *
+ * `max_input_tokens` is the field; there is no `context_window` in the response. Every failure
+ * mode — no network, a key that was revoked, a model id the API does not serve, a token whose
+ * scopes do not reach this endpoint, a 429 — resolves to `null` rather than throwing: this is
+ * called while ingesting a session, and a session must not stop streaming because a catalogue
+ * lookup did not come back.
+ */
+export async function liveContextWindow(model: string, credential: ModelCredential): Promise<number | null> {
+  const id = apiModelId(model)
+  if (!id) return null
+
+  const hit = memo.get(id)
+  if (hit && (hit.window !== null || Date.now() - hit.at < MISS_TTL_MS)) return hit.window
+
+  let window: number | null = null
+  try {
+    const res = await fetch(`${MODELS_ENDPOINT}/${encodeURIComponent(id)}`, {
+      headers: { ...authHeaders(credential), "anthropic-version": "2023-06-01" },
+      signal: AbortSignal.timeout(LOOKUP_TIMEOUT_MS),
+    })
+    if (res.ok) {
+      const body = (await res.json()) as { max_input_tokens?: unknown }
+      const max = Number(body?.max_input_tokens)
+      if (Number.isFinite(max) && max > 0) window = Math.trunc(max)
+    }
+  } catch {
+    // Left as null. The catalogue is the fallback and the caller already knows that.
+  }
+  memo.set(id, { window, at: Date.now() })
+  return window
+}
+
+/**
+ * The window to record for a session that opened on `model`, best source first.
+ *
+ * The `[1m]` suffix wins outright: it is a statement about *this session* (the harness opted it
+ * into a long window), where the catalogue and the API both report a property of the model. For
+ * everything else the API's `max_input_tokens` is preferred over the table, and the table is the
+ * fallback — including when the task carries no Anthropic credential at all, which is an ordinary
+ * case and not an error.
+ */
+export async function resolveContextWindow(
+  model: string | null | undefined,
+  credential: ModelCredential | null | undefined,
+): Promise<number | null> {
+  if (typeof model !== "string" || !model) return null
+  if (model.includes(LONG_CONTEXT_SUFFIX)) return 1_000_000
+  const catalogued = contextWindowOf(model)
+  if (!credential?.value) return catalogued
+  return (await liveContextWindow(model, credential)) ?? catalogued
+}

package/src/catalogs/index.ts

@@ -0,0 +1,216 @@
+// The curated devcontainer catalogs: what a project picker offers before anyone types anything.
+//
+// Data, not logic — but shared data, because the alternative is what happened: two hand-maintained
+// copies that drifted. Spunto Lite's copy was missing `java`, `kubectl-helm-minikube` and
+// `google-cloud-cli`, and described `common-utils` as installing Oh My Zsh at a time when the image
+// recipe explicitly passes `installOhMyZsh: false`. Nobody decided either of those; they are the
+// shape of a catalog nobody owns.
+//
+// **Project templates are deliberately not here.** Spunto Cloud's templates clone a starter
+// repository from GitHub and carry onboarding-gallery presentation (logo, accent, category); Lite's
+// only configure an environment. They answer different questions and diverge on purpose — the test
+// from the README applies, and they fail it.
+
+import type { ExtensionSuggestion } from "../extensions/extensions"
+
+/** A base image of the catalog. */
+export type DevImage = {
+  id: string
+  label: string
+  image: string
+  description: string
+}
+
+/** One configurable option of a feature, as the catalog advertises it. */
+export type DevFeatureOption = {
+  name: string
+  default: string
+  description: string
+}
+
+export type DevFeature = {
+  id: string
+  label: string
+  /** OCI reference the feature is installed from. Mutually exclusive with `localScript`. */
+  ociRef?: string
+  /** Filename of an install script the platform ships itself. Takes precedence over `ociRef`. */
+  localScript?: string
+  description: string
+  /** Options a user may configure. */
+  options?: DevFeatureOption[]
+  /** Options always passed to the install script. A user's choice is merged over these. */
+  defaultOptions?: Record<string, string>
+}
+
+export const AVAILABLE_IMAGES: DevImage[] = [
+  {
+    id: "typescript-node-20",
+    label: "Node.js 20 (TypeScript)",
+    image: "mcr.microsoft.com/devcontainers/typescript-node:20",
+    description: "Node.js 20 + TypeScript, npm/yarn/pnpm",
+  },
+  {
+    id: "javascript-node-20",
+    label: "Node.js 20 (JavaScript)",
+    image: "mcr.microsoft.com/devcontainers/javascript-node:20",
+    description: "Node.js 20, npm/yarn/pnpm",
+  },
+  {
+    id: "python-312",
+    label: "Python 3.12",
+    image: "mcr.microsoft.com/devcontainers/python:3.12",
+    description: "Python 3.12, pip, conda",
+  },
+  {
+    id: "go-121",
+    label: "Go 1.21",
+    image: "mcr.microsoft.com/devcontainers/go:1.21",
+    description: "Go 1.21, go tools",
+  },
+  {
+    id: "rust",
+    label: "Rust",
+    image: "mcr.microsoft.com/devcontainers/rust:latest",
+    description: "Rust stable, cargo",
+  },
+  {
+    id: "java-21",
+    label: "Java 21",
+    image: "mcr.microsoft.com/devcontainers/java:21",
+    description: "Java 21 (JDK), Maven, Gradle",
+  },
+]
+
+/**
+ * Curated devcontainer features. Install scripts are fetched from their OCI ref at image-build
+ * time — see the image recipe for how, and for the two that are always installed whether or not
+ * they appear here.
+ */
+export const AVAILABLE_FEATURES: DevFeature[] = [
+  {
+    id: "docker-in-docker",
+    label: "Docker-in-Docker",
+    // Fork of ghcr.io/devcontainers/features/docker-in-docker (github.com/coderhammer/features).
+    // Upstream resolves "latest" for buildx/compose/compose-switch via git tags and optimistically
+    // downloads an asset named after that tag — breaks whenever a tag is pushed before its release
+    // asset is published (happened with docker/buildx v0.35.0 / v0.35.0-rc1, 404ing the whole
+    // feature install). Our fork verifies the release asset exists before committing to a version.
+    ociRef: "ghcr.io/coderhammer/features/docker-in-docker:3",
+    description: "Docker Engine inside the container (DinD)",
+    options: [
+      { name: "version", default: "latest", description: "Docker/Moby Engine version" },
+    ],
+    // moby-cli is unavailable on Debian trixie and newer — use official Docker instead
+    defaultOptions: { moby: "false" },
+  },
+  {
+    id: "claude-code",
+    label: "Claude Code",
+    ociRef: "ghcr.io/stu-bell/devcontainer-features/claude-code:0",
+    description: "Claude code inside the container"
+  },
+  {
+    id: "node",
+    label: "Node.js",
+    ociRef: "ghcr.io/devcontainers/features/node:1",
+    description: "Node.js, nvm, yarn, pnpm",
+    options: [
+      { name: "version", default: "lts", description: "Node.js version (lts, 20, 22, etc.)" },
+    ],
+  },
+  {
+    id: "python",
+    label: "Python",
+    ociRef: "ghcr.io/devcontainers/features/python:1",
+    description: "Python, pip, venv",
+    options: [
+      { name: "version", default: "latest", description: "Python version" },
+    ],
+  },
+  {
+    id: "go",
+    label: "Go",
+    ociRef: "ghcr.io/devcontainers/features/go:1",
+    description: "Go compiler and tools",
+    options: [
+      { name: "version", default: "latest", description: "Go version" },
+    ],
+  },
+  {
+    id: "rust",
+    label: "Rust",
+    ociRef: "ghcr.io/devcontainers/features/rust:1",
+    description: "Rust, cargo, rustup",
+    options: [
+      { name: "version", default: "latest", description: "Rust version" },
+    ],
+  },
+  {
+    id: "java",
+    label: "Java",
+    ociRef: "ghcr.io/devcontainers/features/java:1",
+    description: "JDK, Maven, Gradle",
+    options: [
+      { name: "version", default: "latest", description: "Java version" },
+    ],
+  },
+  {
+    id: "aws-cli",
+    label: "AWS CLI",
+    ociRef: "ghcr.io/devcontainers/features/aws-cli:1",
+    description: "AWS CLI v2",
+  },
+  {
+    id: "github-cli",
+    label: "GitHub CLI",
+    ociRef: "ghcr.io/devcontainers/features/github-cli:1",
+    description: "GitHub CLI (gh)",
+  },
+  {
+    id: "kubectl-helm-minikube",
+    label: "kubectl + Helm",
+    ociRef: "ghcr.io/devcontainers/features/kubectl-helm-minikube:1",
+    description: "Kubernetes CLI, Helm, Minikube",
+  },
+  {
+    id: "terraform",
+    label: "Terraform",
+    ociRef: "ghcr.io/devcontainers/features/terraform:1",
+    description: "HashiCorp Terraform CLI",
+  },
+  {
+    id: "google-cloud-cli",
+    label: "Google Cloud CLI",
+    localScript: "google-cloud-cli.sh",
+    description: "gcloud, gsutil, bq (local install script)",
+  },
+  {
+    // Always installed, whether or not it's picked here (lib/setup-script.ts § the two features
+    // every worker image is made of): it's what creates the `vscode` user. Listed anyway so a
+    // project can override its options — they're merged over ours rather than installed twice.
+    id: "common-utils",
+    label: "Common Utilities",
+    ociRef: "ghcr.io/devcontainers/features/common-utils:2",
+    description: "zsh, git, curl, etc. — already in every image; pick it to tune its options",
+  },
+]
+
+// Default state of the extension picker, served when the org-scoped route is called without a query.
+//
+// Ids only, no registry URLs: the catalog is registry-agnostic, so the route attaches links for
+// whichever registry the org is on (`withRegistryUrls`). The bar for being listed here is being
+// published on Open VSX — the default registry, and the one every org gets with no configuration.
+// Re-check with:
+//   curl -s https://open-vsx.org/api/<publisher>/<name> | head -c 200
+// (a 404 means the id isn't on Open VSX — drop it or swap it for the equivalent that is, so the
+// defaults stay installable without any extra configuration).
+export const SUGGESTED_EXTENSIONS: ExtensionSuggestion[] = [
+  { id: "esbenp.prettier-vscode", label: "Prettier - Code formatter", publisher: "esbenp" },
+  { id: "dbaeumer.vscode-eslint", label: "ESLint", publisher: "dbaeumer" },
+  { id: "ms-python.python", label: "Python", publisher: "ms-python" },
+  { id: "golang.go", label: "Go", publisher: "golang" },
+  { id: "rust-lang.rust-analyzer", label: "rust-analyzer", publisher: "rust-lang" },
+  { id: "bradlc.vscode-tailwindcss", label: "Tailwind CSS IntelliSense", publisher: "bradlc" },
+  { id: "eamodio.gitlens", label: "GitLens — Git supercharged", publisher: "eamodio" },
+  { id: "ms-azuretools.vscode-docker", label: "Docker", publisher: "ms-azuretools" },
+]

package/src/index.ts

@@ -9,3 +9,7 @@ export * from "./steps/index"
 export * from "./extensions/index"
 export * from "./naming/index"
 export * from "./spec/index"
+export * from "./types/index"
+export * from "./catalogs/index"
+export * from "./script/index"
+export * from "./agent-stream/index"

package/src/script/index.ts

@@ -0,0 +1,30 @@
+// Turning a project's spec into the shell a worker runs.
+//
+// Four generators, one recipe. `buildImageScript` bakes the project image (features, extensions);
+// `buildSetupScript` is the first boot (credentials, dotfiles, clones, postCreate);
+// `buildStartScript` is every boot (code-server, entrypoints, postStart); `buildWorkerScript`
+// assembles the container CMD from the two.
+//
+// Pure string generation — no filesystem, no Docker, no clock. What the scripts *write* (the status
+// file, the extensions directory, the entrypoints list) is named in `../naming`, and what they
+// *print* so a control plane can follow along is in `../steps`.
+//
+// `buildContainerScript` and `buildSetupPlan` are shaped by one product's model — an agent that
+// orchestrates setup phase by phase instead of a container that runs one long CMD (Spunto Cloud,
+// RFC 0017). They live here anyway because they share every helper in the file; splitting them out
+// would fork the helpers, which is the duplication this package exists to remove.
+
+export {
+  buildContainerScript,
+  buildImageScript,
+  buildSetupPlan,
+  buildSetupScript,
+  buildStartScript,
+  buildWorkerScript,
+  defaultVscodeUserSettings,
+  IMAGE_RECIPE_VERSION,
+  resolveRepoBranch,
+} from "./setup-script"
+export type { ResolvedFeature, SetupPhase, SetupScriptParams, StartScriptParams } from "./setup-script"
+
+export { LOCAL_FEATURE_SCRIPTS, localFeatureScript } from "./local-features"

package/src/script/local-features.ts

@@ -0,0 +1,39 @@
+// Install scripts the platform ships itself, for features that have no usable OCI release.
+//
+// Embedded as strings rather than read from disk: the package does no I/O (see the README), and a
+// build script that inlines its own payload is also a build script that cannot fail on a missing
+// file. There is one today, and one is the right number — a local script is a maintenance burden
+// the devcontainer ecosystem is supposed to carry, so the bar for adding another is "the upstream
+// feature does not exist or is broken", not "this was quicker".
+//
+// Keyed by the catalog's `localScript` filename so the two stay legible together.
+
+export const LOCAL_FEATURE_SCRIPTS: Record<string, string> = {
+  // Google's own apt repository; the upstream devcontainer feature pins a gcloud version and
+  // breaks whenever Google retires it.
+  "google-cloud-cli.sh": `#!/bin/sh
+set -e
+
+echo "[feature] google-cloud-cli: installing..."
+
+apt-get update -y -qq
+apt-get install -y -qq apt-transport-https ca-certificates gnupg curl
+
+# Modern apt key setup (no deprecated apt-key)
+curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg \
+  | gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
+
+echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" \
+  | tee /etc/apt/sources.list.d/google-cloud-sdk.list
+
+apt-get update -y -qq
+apt-get install -y -qq google-cloud-cli
+
+echo "[feature] google-cloud-cli: $(gcloud --version | head -1)"
+`,
+}
+
+/** The script a catalog entry's `localScript` names, or undefined if the platform has no such script. */
+export function localFeatureScript(filename: string): string | undefined {
+  return LOCAL_FEATURE_SCRIPTS[filename]
+}