headlesscode 1.0.2

package/src/llm/preflight.ts

@@ -0,0 +1,367 @@
+/**
+ * Preflight probe for `orchestrate` (issue #13).
+ *
+ * Before ANY worker is spawned, make one cheap 1-token completion using the
+ * EXACT model + provider pin a real worker will use (the pin is applied by
+ * `buildRequestBody` in src/llm/openrouter.ts for deepseek/* models, so a
+ * probe through `OpenRouterClient.createChatCompletion` reproduces it by
+ * construction — this is the whole point: a naive manual test request WITHOUT
+ * the pin silently routes to a different, reachable provider and gives a
+ * false "it's fine" signal).
+ *
+ * The failure this catches would otherwise only surface 30-80 iterations
+ * (10-15 minutes of wall time and real spend) into a round. The classification
+ * also separates three failure modes a generic error message conflates:
+ *   - the API key is invalid/missing (HTTP 401/403);
+ *   - the OpenRouter account balance is exhausted (402 / insufficient_balance
+ *     in the body or a 200 error envelope);
+ *   - the PINNED provider itself is unreachable/depleted (5xx/429 — distinct
+ *     from account balance; this is the case that misled a real session).
+ *
+ * `--no-preflight` (orchestrate) skips the extra round-trip for CI /
+ * non-interactive contexts; on by default given the cost of getting this
+ * wrong.
+ */
+
+import type { PricingTable } from "../budget/cost.js"
+import { estimateCost, loadPricingTable } from "../budget/cost.js"
+import { OllamaClient, DEFAULT_OLLAMA_URL } from "./ollama.js"
+import { OpenRouterClient, OpenRouterError, OPENROUTER_BASE_URL, DEFAULT_MODEL } from "./openrouter.js"
+import type { LlmRequest } from "../engine/types.js"
+
+/**
+ * Outcome of the preflight probe. `"ok"` is the only status that means
+ * "spawn the round"; everything else is a distinct, diagnosable failure.
+ */
+export type PreflightStatus = "ok" | "no-api-key" | "invalid-key" | "balance" | "provider" | "network" | "other"
+
+export interface PreflightResult {
+	status: PreflightStatus
+	/** The model id the probe ran with (the exact model a worker would use). */
+	model: string
+	/** The OpenRouter base URL probed. */
+	baseUrl: string
+	/** A single clear, human-readable preflight line (for the CLI + dashboard). */
+	line: string
+	/** Probe wall time, ms. */
+	latencyMs: number
+	/** Estimated USD cost of the 1-token probe itself. */
+	probeCostUsd: number
+	/**
+	 * Order-of-magnitude estimate of the round's LLM cost (nominal per-session
+	 * token profile × worker session count × the model's price). undefined when
+	 * the caller didn't provide a worker session count.
+	 */
+	roundCostEstimateUsd?: number
+}
+
+export interface PreflightOptions {
+	/** The model id a worker would use (defaults to the client default). */
+	model?: string
+	/** API key (default: $HEADLESSCODE_OPENROUTER_API_KEY). */
+	apiKey?: string
+	/** OpenRouter base URL (default: $OPENROUTER_BASE_URL or the built-in). */
+	baseUrl?: string
+	/**
+	 * Number of worker sessions the round will spawn — used for the round cost
+	 * estimate. Omit/0 to skip the estimate.
+	 */
+	workerSessions?: number
+	/**
+	 * Per-session cost cap ($HEADLESSCODE_MAX_COST_USD) — when set, the
+	 * preflight line also shows the round ceiling (cap × sessions).
+	 */
+	maxCostUsd?: number
+	/** Env to read key/base-url from (default: process.env). */
+	env?: NodeJS.ProcessEnv
+	signal?: AbortSignal
+}
+
+/**
+ * Nominal per-session token profile for the round cost estimate. Deliberately
+ * an ORDER-OF-MAGNITUDE heuristic, clearly labeled as such in the output: the
+ * estimate is for deciding whether a round is affordable, not for billing.
+ */
+/** Prefix/first-request size per session (system prompt + tool catalog). */
+export const NOMINAL_SESSION_INPUT_TOKENS = 40_000
+/** Single-request output baseline (kept for compatibility/testing). */
+export const NOMINAL_SESSION_OUTPUT_TOKENS = 10_000
+/** Nominal iterations per worker session for the estimate. */
+export const NOMINAL_SESSION_ITERATIONS = 120
+/** History growth per iteration (tokens) — tool-call turns accumulate. */
+export const NOMINAL_HISTORY_GROWTH_PER_ITERATION = 700
+/** Output tokens per iteration (a tool-call turn, not a big generation). */
+export const NOMINAL_OUTPUT_TOKENS_PER_ITERATION = 1_000
+/**
+ * Cache-hit rate for resends of the growing history. Live rounds measured
+ * ~94% (round1-consolidation 2026-08-16, deepseek-v4-flash) — context resends
+ * are cheap cache reads; only the prefix and misses pay full input price.
+ */
+export const NOMINAL_CACHE_HIT_RATE = 0.9
+
+/**
+ * Estimate the round's LLM cost by modeling the ITERATIVE loop, not a single
+ * request: history grows ~linearly each iteration, so total input ≈
+ * iterations × average-history-size, most of it cache-read; output scales with
+ * iterations. Calibrated against a live 4-worker round (2026-08-16) that
+ * measured $0.09–$0.39/session over 83–241 iterations — the old single-request
+ * model (40k in / 10k out) estimated $0.0336 for the whole round, ~27× under
+ * the ~$0.90 actual. Uses the effective pricing table (defaults +
+ * $HEADLESSCODE_PRICING_JSON overrides), same as the budget guardrail.
+ */
+export function estimateRoundCost(
+	model: string,
+	workerSessions: number,
+	options: { pricing?: PricingTable; env?: NodeJS.ProcessEnv; iterationsPerSession?: number } = {},
+): number {
+	const table = options.pricing ?? loadPricingTable(options.env ?? process.env)
+	const iterations = options.iterationsPerSession ?? NOMINAL_SESSION_ITERATIONS
+	// Average history size over the session ≈ prefix + (iterations/2) × growth.
+	const avgHistoryTokens = NOMINAL_SESSION_INPUT_TOKENS + (iterations / 2) * NOMINAL_HISTORY_GROWTH_PER_ITERATION
+	const totalInputTokens = avgHistoryTokens * iterations
+	const perSession = estimateCost({
+		model,
+		inputTokens: totalInputTokens,
+		cachedTokens: Math.round(totalInputTokens * NOMINAL_CACHE_HIT_RATE),
+		outputTokens: iterations * NOMINAL_OUTPUT_TOKENS_PER_ITERATION,
+		pricing: table,
+	})
+	return perSession * Math.max(1, workerSessions)
+}
+
+/** Round cost ceiling when a per-session cap is configured (cap × sessions). */
+export function roundCostCeilingUsd(workerSessions: number, maxCostUsd?: number): number | undefined {
+	if (maxCostUsd === undefined || !Number.isFinite(maxCostUsd) || maxCostUsd <= 0) {
+		return undefined
+	}
+	return maxCostUsd * Math.max(1, workerSessions)
+}
+
+/** Balance/credit keywords — the highest-signal text signal, checked FIRST. */
+const BALANCE_RE = /insufficient_balance|insufficient balance|insufficient_quota|insufficient quota|payment required|out of credit|out of quota|billing|account balance|402/i
+
+/** Pinned-provider-down language, used to name 5xx/429/200-envelope failures. */
+const PROVIDER_DOWN_RE = /no available providers?|all providers?|provider.*(?:unavailable|down|error|failed)|endpoint.*(?:unavailable|down|error|failed)|upstream|capacity|overloaded|5[0-9]{2}|520|529|530/i
+
+/**
+ * Classify an OpenRouter probe failure into the issue's named failure modes.
+ * Exported for direct unit testing; the text checks run before the status
+ * checks because OpenRouter reports the same underlying problem (e.g. a dead
+ * account) as 402, 429, or a 200-with-error-envelope depending on which
+ * gateway layer answers.
+ */
+export function classifyError(err: unknown): PreflightStatus {
+	if (!(err instanceof OpenRouterError)) {
+		return "other"
+	}
+	const haystack = `${err.message} ${err.body ?? ""}`
+	if (BALANCE_RE.test(haystack)) {
+		return "balance"
+	}
+	if (err.status === 401 || err.status === 403) {
+		return "invalid-key"
+	}
+	if (err.status === 402) {
+		return "balance"
+	}
+	if (err.status === 429 || (err.status !== undefined && err.status >= 500)) {
+		// 429 = OpenRouter's "no available provider / capacity" signal (with
+		// allow_fallbacks:false the pinned provider's own quota/depletion
+		// surfaces here); 5xx = the upstream endpoint or the OpenRouter
+		// gateway failed. Both are "the pinned endpoint isn't serving right
+		// now", distinct from the account-balance case above.
+		return "provider"
+	}
+	if (err.status === undefined) {
+		if (/^Network error/.test(err.message)) {
+			return "network"
+		}
+		if (PROVIDER_DOWN_RE.test(haystack)) {
+			return "provider"
+		}
+		return "other"
+	}
+	return "other"
+}
+
+function resolveBaseUrl(options: PreflightOptions): string {
+	const env = options.env ?? process.env
+	return (options.baseUrl ?? env.OPENROUTER_BASE_URL ?? OPENROUTER_BASE_URL).replace(/\/+$/, "")
+}
+
+function excerpt(text: string, max = 160): string {
+	const t = text.trim().replace(/\s+/g, " ")
+	return t.length > max ? `${t.slice(0, max)}…` : t
+}
+
+/** Compose the single human-readable preflight line for a result. */
+export function buildPreflightLine(
+	result: Omit<PreflightResult, "line"> & { workerSessions: number; maxCostUsd?: number },
+): string {
+	const { status, model, latencyMs, probeCostUsd, roundCostEstimateUsd, workerSessions, maxCostUsd } = result
+	const pinNote = model.startsWith("deepseek/") ? ' (pinned to provider "deepseek")' : ""
+	const costPart =
+		roundCostEstimateUsd !== undefined
+			? `; estimated round cost ≈ $${roundCostEstimateUsd.toFixed(3)} (${workerSessions} worker session(s), order-of-magnitude)`
+			: ""
+	const ceiling = roundCostCeilingUsd(workerSessions, maxCostUsd)
+	const ceilingPart = ceiling !== undefined ? `; per-session cap $${maxCostUsd} → round ceiling $${ceiling.toFixed(3)}` : ""
+
+	switch (status) {
+		case "ok":
+			return (
+				`${model}${pinNote}: all clear — 1-token probe OK in ${latencyMs}ms (probe ≈ $${probeCostUsd.toFixed(6)})` +
+				costPart +
+				ceilingPart
+			)
+		case "no-api-key":
+			return "HEADLESSCODE_OPENROUTER_API_KEY is not set — workers cannot reach OpenRouter"
+		case "invalid-key":
+			return `${model}${pinNote}: API key invalid or unauthorized (HTTP 401/403) — check HEADLESSCODE_OPENROUTER_API_KEY`
+		case "balance":
+			return `${model}${pinNote}: OpenRouter account balance exhausted (insufficient_balance / HTTP 402) — top up the account before spawning workers`
+		case "provider":
+			return `${model}${pinNote}: pinned provider unreachable or depleted (HTTP 5xx/429) — distinct from account balance; the pinned official endpoint is not serving this model right now`
+		case "network":
+			return `network error reaching OpenRouter (${result.baseUrl}) — check connectivity`
+		default:
+			return `${model}${pinNote}: preflight probe failed with an unexpected error — inspect the message`
+	}
+}
+
+/**
+ * Run the preflight probe. Never throws: every failure mode is folded into a
+ * `PreflightResult` with a clear status + line (the CLI aborts on any
+ * non-"ok" status).
+ */
+export async function runPreflight(options: PreflightOptions): Promise<PreflightResult> {
+	const env = options.env ?? process.env
+	const apiKey = options.apiKey ?? env.HEADLESSCODE_OPENROUTER_API_KEY
+	const model = (options.model?.trim() || DEFAULT_MODEL).trim()
+	const baseUrl = resolveBaseUrl(options)
+	const workerSessions = Math.max(1, options.workerSessions ?? 0)
+	const roundCostEstimateUsd =
+		options.workerSessions !== undefined && options.workerSessions > 0 ? estimateRoundCost(model, workerSessions, { env }) : undefined
+
+	if (!apiKey) {
+		const result: PreflightResult = {
+			status: "no-api-key",
+			model,
+			baseUrl,
+			line: "",
+			latencyMs: 0,
+			probeCostUsd: 0,
+			roundCostEstimateUsd,
+		}
+		result.line = buildPreflightLine({ ...result, workerSessions, maxCostUsd: options.maxCostUsd })
+		return result
+	}
+
+	const client = new OpenRouterClient({ apiKey, baseUrl, defaultModel: model })
+	const startedAt = Date.now()
+	let status: PreflightStatus
+	let probeCostUsd = 0
+	let detail = ""
+	try {
+		const probeRequest: LlmRequest = {
+			model,
+			messages: [{ role: "user", content: "ping" }],
+			maxTokens: 1,
+			temperature: 0,
+			signal: options.signal,
+		}
+		const response = await client.createChatCompletion(probeRequest)
+		status = "ok"
+		const usage = response.usage
+		probeCostUsd = estimateCost({
+			model,
+			inputTokens: usage?.promptTokens ?? 0,
+			outputTokens: usage?.completionTokens ?? 0,
+			cachedTokens: usage?.cachedTokens ?? 0,
+		})
+	} catch (err) {
+		status = classifyError(err)
+		detail = err instanceof Error ? err.message : String(err)
+	}
+	const latencyMs = Date.now() - startedAt
+
+	const result: PreflightResult = {
+		status,
+		model,
+		baseUrl,
+		line: "",
+		latencyMs,
+		probeCostUsd,
+		roundCostEstimateUsd,
+	}
+	const line = buildPreflightLine({ ...result, workerSessions, maxCostUsd: options.maxCostUsd })
+	result.line = status === "ok" ? line : `${line} — ${excerpt(detail)}`
+	return result
+}
+
+/**
+ * Local-backend counterpart to `runPreflight` — 2026-08-27: `orchestrate`
+ * unconditionally ran the OpenRouter probe above even when a round's worker/
+ * reviewer/QA mode was configured for the local Ollama-compat daemon
+ * (`useLocalCodeBackend` in cli.ts), so switching a project fully to local
+ * inference made every `orchestrate` invocation fail preflight against a
+ * cloud key/model that round was never going to use (verified live: a round
+ * with only local env vars set still probed `deepseek/deepseek-v4-flash-0731`
+ * and aborted on a stale/invalid OpenRouter key that was irrelevant to the
+ * actual run). This does the same "one cheap real completion before spawning
+ * anything" check, but against the local daemon — catching the daemon being
+ * down, the model not loaded, or a wrong base URL before burning iterations
+ * on it, the same value `runPreflight` provides for the cloud path.
+ *
+ * Deliberately NOT a variant of `PreflightStatus` above (no-api-key/balance/
+ * provider-pin are cloud-specific concepts with no local equivalent) — a
+ * local daemon is either reachable-and-generating or it isn't.
+ */
+export type LocalPreflightStatus = "ok" | "unreachable" | "other"
+
+export interface LocalPreflightResult {
+	status: LocalPreflightStatus
+	model: string
+	baseUrl: string
+	line: string
+	latencyMs: number
+}
+
+export interface LocalPreflightOptions {
+	/** The model id a worker would use (default: OllamaClient's own default). */
+	model?: string
+	/** Ollama-compat base URL (default: $HEADLESSCODE_OLLAMA_URL or the built-in). */
+	baseUrl?: string
+	env?: NodeJS.ProcessEnv
+	signal?: AbortSignal
+}
+
+export async function runLocalPreflight(options: LocalPreflightOptions): Promise<LocalPreflightResult> {
+	const env = options.env ?? process.env
+	const baseUrl = (options.baseUrl ?? env.HEADLESSCODE_OLLAMA_URL ?? DEFAULT_OLLAMA_URL).replace(/\/+$/, "")
+	const model = options.model?.trim() || "(daemon default)"
+	const client = new OllamaClient({ baseUrl, defaultModel: options.model })
+	const startedAt = Date.now()
+	let status: LocalPreflightStatus
+	let detail = ""
+	try {
+		await client.createChatCompletion({
+			model,
+			messages: [{ role: "user", content: "ping" }],
+			maxTokens: 1,
+			temperature: 0,
+			signal: options.signal,
+		})
+		status = "ok"
+	} catch (err) {
+		detail = err instanceof Error ? err.message : String(err)
+		const cause = err instanceof Error ? (err.cause as { code?: string } | undefined) : undefined
+		status = /ECONNREFUSED|ENOTFOUND|fetch failed|is the daemon running/i.test(detail) || cause?.code === "ECONNREFUSED" ? "unreachable" : "other"
+	}
+	const latencyMs = Date.now() - startedAt
+	const line =
+		status === "ok"
+			? `${model} @ ${baseUrl}: all clear — 1-token probe OK in ${latencyMs}ms (local daemon, $0)`
+			: `${model} @ ${baseUrl}: ${status === "unreachable" ? "daemon unreachable" : "probe failed"} — ${excerpt(detail)}`
+	return { status, model, baseUrl, line, latencyMs }
+}

package/src/llm/transcript-capture.ts

@@ -0,0 +1,84 @@
+/**
+ * Opt-in, full-fidelity LLM call transcript capture — the prerequisite for
+ * ever fine-tuning/distilling on this project's own sessions.
+ *
+ * `.headlesscode/events/*.jsonl` (see src/engine/loop.ts's eventFeed) is a
+ * lightweight MONITORING log, not a training-data source: verified live
+ * 2026-08-27 that a `write_to_file` tool call there logs only the target
+ * file path, never the content the model actually generated. It answers
+ * "what happened" (which is all it was ever built for) but not "what did
+ * the model actually write" — the second one is what imitation-based
+ * fine-tuning needs. This module captures the real thing: the exact
+ * `LlmRequest.messages` sent and the exact `LlmResponse` received, for
+ * every call, from both providers (OllamaClient and OpenRouterClient) —
+ * so a DeepSeek session's successful trajectory and a Qwen session's
+ * failing one on the same task become directly comparable training pairs.
+ *
+ * Off by default (matches this project's convention for every experimental
+ * feature — see e.g. HEADLESSCODE_LOCAL_EXPLORE's own doc comment). Opt in
+ * with HEADLESSCODE_CAPTURE_TRANSCRIPT_DIR set to a directory; one JSONL
+ * file per provider per UTC day, so a long-running orchestrate invocation
+ * doesn't produce thousands of tiny files. Capture failures are swallowed
+ * (never allowed to break a real LLM call over a logging side effect).
+ */
+
+import * as fs from "node:fs"
+import * as path from "node:path"
+import type { ChatMessage, ChatTool, LlmResponse } from "../engine/types.js"
+
+export const TRANSCRIPT_CAPTURE_DIR_ENV = "HEADLESSCODE_CAPTURE_TRANSCRIPT_DIR"
+
+export function isTranscriptCaptureEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+	return Boolean(env[TRANSCRIPT_CAPTURE_DIR_ENV]?.trim())
+}
+
+export interface TranscriptContext {
+	/** "ollama" | "openrouter" — which client made this call. */
+	provider: "ollama" | "openrouter"
+	/** Resolved model id actually used for the call. */
+	model: string
+	/** Session/task identifiers, when the caller has them, purely for later
+	 *  filtering/joining against harness.log — never required. */
+	sessionId?: string
+	mode?: string
+	workspaceRoot?: string
+}
+
+export interface TranscriptOutcome {
+	/** Full engine-level request messages, exactly as sent (post-condensation,
+	 *  pre-wire-format-translation — the same shape fed back into the next
+	 *  turn, which is what a training example needs to reproduce). */
+	messages: ChatMessage[]
+	tools?: ChatTool[]
+	temperature?: number
+	/** Present on success. */
+	response?: LlmResponse
+	/** Present on failure — the error message, not a thrown object. */
+	error?: string
+	durationMs: number
+}
+
+/**
+ * Append one call's full request/response to today's capture file for this
+ * provider. Fire-and-forget: never throws, never awaited by the caller —
+ * a capture failure must not affect the real LLM call it's recording.
+ */
+export function captureTranscript(context: TranscriptContext, outcome: TranscriptOutcome): void {
+	const dir = process.env[TRANSCRIPT_CAPTURE_DIR_ENV]?.trim()
+	if (!dir) {
+		return
+	}
+	try {
+		fs.mkdirSync(dir, { recursive: true })
+		const day = new Date().toISOString().slice(0, 10)
+		const filePath = path.join(dir, `${context.provider}-${day}.jsonl`)
+		const record = {
+			ts: new Date().toISOString(),
+			...context,
+			...outcome,
+		}
+		fs.appendFileSync(filePath, `${JSON.stringify(record)}\n`, "utf-8")
+	} catch {
+		// Never let a capture failure affect the real call.
+	}
+}

package/src/memory/embed.ts

@@ -0,0 +1,110 @@
+/**
+ * Local embedder — Phase 3 placeholder for a real local embedding model.
+ *
+ * `createLocalEmbedder()` returns a dependency-free, deterministic embedder:
+ * the text is tokenized into lowercase word tokens + character bigrams, each
+ * token is hashed into a fixed-dimension vector (default 256) with a stable
+ * 32-bit hash, and the vector is L2-normalized. Cosine similarity over these
+ * vectors gives a cheap lexical-overlap similarity signal.
+ *
+ * This is the ZERO-DEPENDENCY stand-in the spec calls for (a local embedding
+ * model with no cloud routing / no rate limiter / no encryption). A real local
+ * embedding model can be swapped in behind the `Embedder` interface
+ * (src/memory/types.ts) later WITHOUT touching any caller.
+ *
+ * Determinism guarantees:
+ *   - Same input string → same vector (across calls AND across processes).
+ *   - No Math.random, no platform-dependent iteration order.
+ *   - Hashing is pure FNV-1a; dims must be ≥ 1.
+ */
+
+import type { Embedder } from "./types.js"
+
+/** FNV-1a 32-bit hash — pure, deterministic, platform-independent. */
+export function fnv1a(text: string): number {
+	let hash = 0x811c9dc5
+	for (let i = 0; i < text.length; i++) {
+		hash ^= text.charCodeAt(i)
+		hash = Math.imul(hash, 0x01000193)
+	}
+	return hash >>> 0
+}
+
+/**
+ * Tokenize into lowercase word tokens (len > 1) + character bigrams of the
+ * lowercased string. Deterministic order: words first, then bigrams.
+ */
+export function tokenize(text: string): string[] {
+	const lower = text.toLowerCase()
+	const words = lower.match(/[a-z0-9]+/g) ?? []
+	const tokens = words.filter((w) => w.length > 1)
+	for (let i = 0; i + 1 < lower.length; i++) {
+		const bigram = lower.slice(i, i + 2)
+		if (/[a-z0-9]/.test(bigram[0]) && /[a-z0-9]/.test(bigram[1])) {
+			tokens.push(bigram)
+		}
+	}
+	return tokens
+}
+
+/**
+ * Create a deterministic local embedder.
+ *
+ * @param dims  fixed vector dimension (default 256). Must be a positive int.
+ */
+export function createLocalEmbedder(dims = 256): Embedder {
+	if (!Number.isInteger(dims) || dims <= 0) {
+		throw new Error(`createLocalEmbedder: dims must be a positive integer (got ${dims})`)
+	}
+	return {
+		embed(text: string): number[] {
+			const vector = new Array<number>(dims).fill(0)
+			for (const token of tokenize(text)) {
+				vector[fnv1a(token) % dims] += 1
+			}
+			return l2Normalize(vector)
+		},
+	}
+}
+
+/**
+ * Cosine similarity between two vectors. Zero vectors (or zero norms) yield 0.
+ * Handles different lengths by treating missing entries as 0.
+ */
+export function cosine(a: number[], b: number[]): number {
+	let dot = 0
+	let normA = 0
+	let normB = 0
+	const len = Math.max(a.length, b.length)
+	for (let i = 0; i < len; i++) {
+		const av = a[i] ?? 0
+		const bv = b[i] ?? 0
+		dot += av * bv
+		normA += av * av
+		normB += bv * bv
+	}
+	if (normA === 0 || normB === 0) {
+		return 0
+	}
+	return dot / (Math.sqrt(normA) * Math.sqrt(normB))
+}
+
+/** Convenience: cosine similarity of two texts through an embedder. */
+export function similarity(embedder: Embedder, a: string, b: string): number {
+	return cosine(embedder.embed(a), embedder.embed(b))
+}
+
+function l2Normalize(vector: number[]): number[] {
+	let norm = 0
+	for (const v of vector) {
+		norm += v * v
+	}
+	if (norm === 0) {
+		return vector
+	}
+	const scale = 1 / Math.sqrt(norm)
+	for (let i = 0; i < vector.length; i++) {
+		vector[i] *= scale
+	}
+	return vector
+}

package/src/memory/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Phase 3 memory subsystem — public API boundary.
+ *
+ * Re-exports the memory contracts, the fully working local backend, the local
+ * embedder, the deterministic summarizer, and the UwUChat client stub so
+ * callers (HeadlessSession, the CLI, and future consumers) depend on this
+ * module — never on file paths into `src/memory/`.
+ */
+
+export * from "./types.js"
+export { LocalMemoryStore, sanitizeProject, type LocalMemoryStoreOptions } from "./local.js"
+export { createLocalEmbedder, cosine, similarity, fnv1a, tokenize } from "./embed.js"
+export {
+	extractSessionSummary,
+	extractFacts,
+	buildRollingSummary,
+	classifyLine,
+	NoopSummarizer,
+	type SummarizeWithLlm,
+	type ExtractSummaryOptions,
+} from "./summarizer.js"
+export { UwUChatMemoryStore, UwUChatMemoryError, API_PREFIX, type UwUChatMemoryOptions } from "./uwuchat.js"