@spunto/build 0.10.0 → 0.12.0

package/README.md

@@ -12,6 +12,8 @@ on*.
 npm install @spunto/build
 ```
 
+**Documentation: https://spunto.net/documentation/packages/build**
+
 ## What's in it
 
 ### `@spunto/build/steps` — the build-log protocol

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/build",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Spunto's shared Build engine — the devcontainer image protocol and VS Code extension registry clients, with no database, no HTTP framework and no UI.",
   "type": "module",
   "license": "MIT",

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

@@ -122,6 +122,37 @@ export function interruptLine(protocol: AgentProtocol, requestId: string): strin
   return `${JSON.stringify({ type: "control_request", request_id: requestId, request: { subtype: "interrupt" } })}\n`
 }
 
+/**
+ * Ask the harness to **name the conversation**, or null for a dialect that cannot be asked.
+ *
+ * Claude Code used to do this on its own within seconds of the first turn, headless included —
+ * that title is what `sessionTitleProbe` reads. Measured on 2.1.296 (October 2026), it no longer
+ * does for a session driven over `--input-format stream-json`: the transcript gets `atis-latch`
+ * and `last-prompt` lines and never an `ai-title`, so every task kept its placeholder. What it
+ * still answers is the SDK's own `generate_session_title` control request — the call its
+ * TypeScript SDK makes — with `{"title":…}` in a `control_response` on stdout, and `persist`
+ * writes the same `ai-title` line to the transcript as before.
+ *
+ * Asking is not naming: the harness still picks the words, from the human's prompt (the
+ * `description`), exactly as it would have unprompted. Nothing of ours ends up in the title.
+ *
+ * The request id carries `TITLE_REQUEST_PREFIX` so the answer can be told apart from every other
+ * `control_response` (an interrupt's, say) without keeping state between write and read.
+ */
+export function sessionTitleRequestLine(protocol: AgentProtocol, requestId: string, description: string): string | null {
+  if (protocol !== "claude-stream") return null
+  const text = description.trim()
+  if (!text) return null
+  return `${JSON.stringify({
+    type: "control_request",
+    request_id: `${TITLE_REQUEST_PREFIX}${requestId}`,
+    request: { subtype: "generate_session_title", description: text, persist: true },
+  })}\n`
+}
+
+/** Marks the `control_request`s that ask for a title, and so the `control_response`s that answer. */
+const TITLE_REQUEST_PREFIX = "spunto-title-"
+
 /**
  * A shell that prints the line where the harness wrote **the name it gave the conversation**, or
  * null for a dialect that has no such thing.
@@ -143,6 +174,9 @@ export function interruptLine(protocol: AgentProtocol, requestId: string): strin
  * `--no-session-persistence` writes no transcript, and then this finds nothing — which is a
  * normal answer, not an error.
  *
+ * Since Claude Code 2.1.296 an interactive session only writes that line once asked
+ * (`sessionTitleRequestLine`); a one-shot `claude-json` run has no stdin to be asked on.
+ *
  * `jsonl` gets no probe on purpose: a harness speaking our vocabulary says the name in band,
  * `{"type":"session.title","title":"…"}`, and pays nothing for it.
  */
@@ -383,6 +417,16 @@ function adaptClaudeJson(obj: Record<string, unknown>): NormalizedEvent[] {
     return events
   }
 
+  // The answer to `sessionTitleRequestLine`. Only ours, recognised by request id: a
+  // `control_response` is also how an interrupt is acknowledged, and that one is no name.
+  if (type === "control_response") {
+    const response = (obj.response ?? {}) as Record<string, unknown>
+    const inner = (response.response ?? {}) as Record<string, unknown>
+    const requestId = typeof response.request_id === "string" ? response.request_id : ""
+    const title = response.subtype === "success" && requestId.startsWith(TITLE_REQUEST_PREFIX) ? cleanTitle(inner.title) : null
+    if (title) return [{ type: "session.title", payload: { title } }]
+  }
+
   // Known-but-uninteresting (`rate_limit_event`, `system/thinking_tokens`) and anything the CLI
   // grows next land here rather than being dropped: an unknown event is information about the
   // harness, and the UI keeps it behind a toggle.

package/src/agent-stream/index.ts

@@ -25,6 +25,7 @@ export {
   parseStreamLine,
   readsTitleOutOfBand,
   sessionTitleProbe,
+  sessionTitleRequestLine,
   splitCompleteLines,
   summarizeUsage,
   TASK_EVENT_TYPES,

package/src/script/index.ts

@@ -21,6 +21,7 @@ export {
   buildSetupScript,
   buildStartScript,
   buildWorkerScript,
+  DEFAULT_IDE_PORT,
   defaultVscodeUserSettings,
   IMAGE_RECIPE_VERSION,
   resolveRepoBranch,

package/src/script/setup-script.ts

@@ -1215,10 +1215,25 @@ export type StartScriptParams = {
    * the image build used. Absent/unusable = Open VSX.
    */
   extensionsGallery?: string | null
+  /**
+   * The port code-server listens on, 8080 by default (what every worker and the proxy's `code` host
+   * assume). For a box where 8080 is taken by the host itself — a Blaxel sandbox's own API.
+   */
+  idePort?: number
+}
+
+/** code-server's port when the caller doesn't say otherwise. */
+export const DEFAULT_IDE_PORT = 8080
+
+function idePortOf(port: number | undefined): number {
+  if (port === undefined) return DEFAULT_IDE_PORT
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`idePort must be a TCP port, got ${port}`)
+  return port
 }
 
 export function buildStartScript(params: StartScriptParams): { script: string; hasDinD: boolean } {
   const { project, sshGatewayPublicKey, colorTabsByProject, extensionsGallery } = params
+  const idePort = idePortOf(params.idePort)
   const homeDir = "/home/vscode"
   const username = "vscode"
 
@@ -1338,7 +1353,7 @@ export function buildStartScript(params: StartScriptParams): { script: string; h
   // ── 4c. Restore the user's PORT secret for code-server's own terminal panel ─
   // code-server reads $PORT to override --bind-addr (see § 5 below), so its
   // whole process tree — including the integrated terminal it spawns — inherits
-  // PORT=8080 unless corrected. `terminal.integrated.env.linux` lets VS Code
+  // PORT=<idePort> unless corrected. `terminal.integrated.env.linux` lets VS Code
   // inject env overrides into terminals it spawns without touching the server
   // process itself, so a `PORT` project secret still reaches the user's shell.
   // Uses code-server's own bundled node (guaranteed present regardless of the
@@ -1387,12 +1402,12 @@ export function buildStartScript(params: StartScriptParams): { script: string; h
     "while true; do",
     '  VSCODE_PROXY_URI="${PUBLIC_PROTOCOL}://${WORKER_SLUG}-{{port}}.${BASE_DOMAIN}" \\',
     // PORT is overridden here (not unset globally) so a project secret named
-    // PORT can't make code-server bind elsewhere. This also leaks PORT=8080
+    // PORT can't make code-server bind elsewhere. This also leaks PORT=<idePort>
     // into code-server's own process tree (its integrated terminal included) —
     // § 4c above restores the original value for that terminal specifically.
     // apps/agent/src/terminal.ts (dashboard's separate terminal feature) is a
     // different process tree entirely and was never affected.
-    "    PORT=8080 code-server --bind-addr 0.0.0.0:8080 --auth none /workspace 2>&1",
+    `    PORT=${idePort} code-server --bind-addr 0.0.0.0:${idePort} --auth none /workspace 2>&1`,
     '  echo "[start] code-server exited ($?), restarting in 3s..."',
     "  sleep 3",
     "done",
@@ -1491,6 +1506,7 @@ export type SetupPhase = {
 // deleted once WORKER_SETUP_ORCHESTRATOR=agent becomes the default. See RFC 0017 §2.1.
 export function buildContainerScript(params: StartScriptParams): { script: string; hasDinD: boolean } {
   const { project, sshGatewayPublicKey, colorTabsByProject, extensionsGallery } = params
+  const idePort = idePortOf(params.idePort)
   const homeDir = "/home/vscode"
   const username = "vscode"
 
@@ -1621,7 +1637,7 @@ export function buildContainerScript(params: StartScriptParams): { script: strin
     ...galleryExport(extensionsGallery),
     "while true; do",
     '  VSCODE_PROXY_URI="${PUBLIC_PROTOCOL}://${WORKER_SLUG}-{{port}}.${BASE_DOMAIN}" \\',
-    "    PORT=8080 code-server --bind-addr 0.0.0.0:8080 --auth none /workspace 2>&1",
+    `    PORT=${idePort} code-server --bind-addr 0.0.0.0:${idePort} --auth none /workspace 2>&1`,
     '  echo "[start] code-server exited ($?), restarting in 3s..."',
     "  sleep 3",
     "done",