@yagni-app/code 0.2.0 → 0.3.0

package/dist/extension/cmux/hooks.js

@@ -0,0 +1,192 @@
+import { normalizedLaunchArgv } from "./dispatcher.js";
+import { firstString, warn } from "./state.js";
+export function eventName(subcommand) {
+    switch (subcommand) {
+        case "session-start": return "SessionStart";
+        case "prompt-submit": return "UserPromptSubmit";
+        case "stop": return "Stop";
+        case "notification": return "Notification";
+        default: return subcommand;
+    }
+}
+const resolvedSurfaceTargets = new WeakMap();
+function surfaceTargetsFor(dispatcher) {
+    let targets = resolvedSurfaceTargets.get(dispatcher);
+    if (!targets) {
+        targets = new Map();
+        resolvedSurfaceTargets.set(dispatcher, targets);
+    }
+    return targets;
+}
+export function surfaceTargetArgs(dispatcher, sessionId) {
+    const resolved = surfaceTargetsFor(dispatcher).get(sessionId);
+    if (resolved)
+        return [...resolved];
+    const surfaceId = firstString(process.env.CMUX_SURFACE_ID);
+    if (!surfaceId)
+        return null;
+    const args = [];
+    const workspaceId = firstString(process.env.CMUX_WORKSPACE_ID);
+    if (workspaceId)
+        args.push("--workspace", workspaceId);
+    args.push("--surface", surfaceId);
+    return args;
+}
+export function rememberSurfaceTarget(dispatcher, sessionId, result) {
+    const payload = parseJSONOutput(result);
+    const workspaceId = firstString(payload?.workspace_id);
+    const surfaceId = firstString(payload?.surface_id);
+    if (!workspaceId || !surfaceId)
+        return;
+    surfaceTargetsFor(dispatcher).set(sessionId, ["--workspace", workspaceId, "--surface", surfaceId]);
+}
+export function releaseSessionRuntime(dispatcher, sessionStates, sessionId) {
+    dispatcher.releaseSession(sessionId);
+    sessionStates.delete(sessionId);
+    surfaceTargetsFor(dispatcher).delete(sessionId);
+}
+function parseJSONOutput(result) {
+    if (!result.ok)
+        return null;
+    try {
+        const parsed = JSON.parse(result.stdout);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function sendHook(dispatcher, subcommand, context, extra = {}) {
+    if (process.env.CMUX_PI_HOOKS_DISABLED === "1")
+        return true;
+    const sessionId = context.sessionId;
+    if (!sessionId)
+        return true;
+    const target = surfaceTargetArgs(dispatcher, sessionId);
+    if (!target)
+        return !firstString(process.env.CMUX_PANEL_ID);
+    const cwd = context.cwd;
+    const payload = {
+        session_id: sessionId,
+        cwd,
+        hook_event_name: eventName(subcommand),
+        event: eventName(subcommand),
+        ...extra,
+    };
+    const result = await dispatcher.run(["hooks", "pi", subcommand, ...target], cwd, JSON.stringify(payload), context);
+    if (result.ok)
+        rememberSurfaceTarget(dispatcher, sessionId, result);
+    if (!result.ok && !result.surfaceUnavailable) {
+        warn(context, "cmux hook command failed", {
+            subcommand,
+            status: result.status,
+            stderr_available: result.stderr.trim().length > 0,
+            error_available: result.error !== undefined,
+        });
+    }
+    return result.ok;
+}
+// --- Resume bindings ---
+const piOptionsWithValue = new Set([
+    "--model", "-m", "--thinking", "--provider", "--extension", "-e",
+    "--skill", "--mcp-config", "--permission-mode", "--session-dir",
+    "--config", "--profile", "--system-prompt", "--append-system-prompt",
+    "--cwd", "--dir", "--trust", "--sandbox",
+]);
+const piOptionsWithoutValue = new Set([
+    "--no-color", "--dangerously-skip-permissions", "--yolo",
+]);
+const piSelectorsToDrop = new Set([
+    "--session", "-s", "--resume", "--fork", "--api-key", "--prompt", "--print",
+]);
+function sanitizedResumeArgv(sessionId) {
+    const raw = normalizedLaunchArgv();
+    const executable = raw[0] || "pi";
+    const out = [executable, "--session", sessionId];
+    for (let index = 1; index < raw.length; index += 1) {
+        const arg = raw[index];
+        if (!arg)
+            continue;
+        if (piSelectorsToDrop.has(arg)) {
+            if (index + 1 < raw.length && !raw[index + 1].startsWith("-"))
+                index += 1;
+            continue;
+        }
+        if (arg.startsWith("--session=") || arg.startsWith("--resume=") ||
+            arg.startsWith("--fork=") || arg.startsWith("--api-key=") ||
+            arg.startsWith("--prompt=")) {
+            continue;
+        }
+        if (piOptionsWithValue.has(arg)) {
+            out.push(arg);
+            if (index + 1 < raw.length) {
+                out.push(raw[index + 1]);
+                index += 1;
+            }
+            continue;
+        }
+        if ([...piOptionsWithValue].some((option) => arg.startsWith(`${option}=`)) || piOptionsWithoutValue.has(arg)) {
+            out.push(arg);
+        }
+    }
+    return out;
+}
+function resumeBindingMatches(payload, sessionId) {
+    const binding = payload?.resume_binding;
+    if (!binding || typeof binding !== "object")
+        return false;
+    const typed = binding;
+    return firstString(typed.kind) === "pi" &&
+        firstString(typed.checkpoint_id, typed.checkpointId) === sessionId;
+}
+export async function ensureResumeBinding(dispatcher, context, sessionId) {
+    if (process.env.CMUX_PI_HOOKS_DISABLED === "1")
+        return;
+    const target = surfaceTargetArgs(dispatcher, sessionId);
+    if (!target)
+        return;
+    const cwd = context.cwd;
+    const resumeArgv = sanitizedResumeArgv(sessionId);
+    const set = await dispatcher.run([
+        "--json", "surface", "resume", "set", ...target,
+        "--name", "Pi", "--kind", "pi", "--checkpoint-id", sessionId,
+        "--source", "agent-hook", "--cwd", cwd, "--", ...resumeArgv,
+    ], cwd, undefined, context);
+    if (!set.ok && !set.surfaceUnavailable) {
+        warn(context, "failed to set Pi resume binding", {
+            status: set.status,
+            stderr_available: set.stderr.trim().length > 0,
+        });
+        return;
+    }
+    if (set.surfaceUnavailable)
+        return;
+    const verification = await dispatcher.run(["--json", "surface", "resume", "get", ...target], cwd, undefined, context);
+    if (verification.surfaceUnavailable)
+        return;
+    const verified = parseJSONOutput(verification);
+    if (!resumeBindingMatches(verified, sessionId)) {
+        warn(context, "Pi resume binding did not verify after write", { session_id: sessionId });
+    }
+}
+export async function clearResumeBinding(dispatcher, context, sessionId) {
+    if (process.env.CMUX_PI_HOOKS_DISABLED === "1")
+        return;
+    const target = surfaceTargetArgs(dispatcher, sessionId);
+    if (!target)
+        return;
+    const cwd = context.cwd;
+    const result = await dispatcher.run([
+        "--json", "surface", "resume", "clear", ...target,
+        "--checkpoint-id", sessionId, "--source", "agent-hook",
+    ], cwd, undefined, context);
+    if (result.surfaceUnavailable)
+        return;
+    if (!result.ok) {
+        warn(context, "failed to clear Pi resume binding", {
+            status: result.status,
+            stderr_available: result.stderr.trim().length > 0,
+        });
+    }
+}
+//# sourceMappingURL=hooks.js.map

package/dist/extension/cmux/index.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export declare function registerCmuxBridge(pi: ExtensionAPI): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/extension/cmux/index.js

@@ -0,0 +1,155 @@
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { CmuxDispatcher } from "./dispatcher.js";
+import { stateFor, snapshotContext, beginTurn, currentTurnId, finishTurn, settleTurn, lastAssistantMessage, firstString, objectValue, warn, } from "./state.js";
+import { sendHook, ensureResumeBinding, clearResumeBinding, releaseSessionRuntime, } from "./hooks.js";
+import { renameWorkspaceFromPrompt } from "./naming.js";
+/** Remove a stale cmux-installed extension so hooks don't double-fire. */
+function removeStaleManagedExtension() {
+    const agentDir = process.env.PI_CODING_AGENT_DIR || process.env.YAGNI_CODING_AGENT_DIR;
+    if (!agentDir)
+        return;
+    const managed = join(agentDir, "extensions", "cmux-session.ts");
+    try {
+        if (!existsSync(managed))
+            return;
+        const head = readFileSync(managed, "utf8").slice(0, 200);
+        if (head.includes("cmux-pi-session-extension-marker")) {
+            unlinkSync(managed);
+            try {
+                unlinkSync(join(agentDir, "extensions", ".cmux-session.lock"));
+            }
+            catch { }
+        }
+    }
+    catch { }
+}
+export function registerCmuxBridge(pi) {
+    if (!process.env.CMUX_SURFACE_ID)
+        return;
+    if (process.env.CMUX_PI_HOOKS_DISABLED === "1")
+        return;
+    const dispatcher = new CmuxDispatcher();
+    const sessionStates = new Map();
+    const lifecycleTails = new Map();
+    const enqueueLifecycleTask = (sessionId, context, operation) => {
+        const previous = lifecycleTails.get(sessionId) || Promise.resolve();
+        let tracked;
+        tracked = previous
+            .then(operation)
+            .then(() => undefined)
+            .catch((error) => {
+            const msg = error instanceof Error ? error.message : undefined;
+            warn(context, "cmux lifecycle task failed", { error_message: msg?.slice(0, 512) }, true);
+        })
+            .finally(() => {
+            if (lifecycleTails.get(sessionId) === tracked)
+                lifecycleTails.delete(sessionId);
+        });
+        lifecycleTails.set(sessionId, tracked);
+        return tracked;
+    };
+    pi.on("session_start", (_event, ctx) => {
+        removeStaleManagedExtension();
+        const context = snapshotContext(ctx);
+        const sessionId = context.sessionId;
+        if (!sessionId)
+            return;
+        const state = stateFor(sessionStates, sessionId);
+        state.pendingCompletion = undefined;
+        state.stopped = false;
+        enqueueLifecycleTask(sessionId, context, async () => {
+            const ok = await sendHook(dispatcher, "session-start", context);
+            if (ok)
+                await ensureResumeBinding(dispatcher, context, sessionId);
+        });
+    });
+    pi.on("before_agent_start", (event, ctx) => {
+        const context = snapshotContext(ctx);
+        const sessionId = context.sessionId;
+        if (!sessionId)
+            return;
+        const turnId = beginTurn(sessionStates, sessionId, event);
+        const st = stateFor(sessionStates, sessionId);
+        if (typeof event.prompt === "string" && event.prompt.trim()) {
+            st.lastPrompt = event.prompt.trim();
+        }
+        enqueueLifecycleTask(sessionId, context, () => sendHook(dispatcher, "prompt-submit", context, { prompt: event.prompt, turn_id: turnId }));
+    });
+    pi.on("agent_end", (event, ctx) => {
+        const context = snapshotContext(ctx);
+        const sessionId = context.sessionId;
+        if (!sessionId)
+            return;
+        const state = stateFor(sessionStates, sessionId);
+        const message = lastAssistantMessage(event);
+        state.pendingCompletion = {
+            lastAssistantMessage: message || state.pendingCompletion?.lastAssistantMessage,
+            notificationType: firstString(objectValue(event, ["stopReason", "reason", "terminationReason"])) || "completed",
+            turnId: currentTurnId(sessionStates, sessionId, event),
+        };
+        // Pi >= 0.80.5 always emits agent_settled, so we wait for it there.
+    });
+    pi.on("agent_settled", (_event, ctx) => {
+        const context = snapshotContext(ctx);
+        try {
+            if (!ctx.isIdle())
+                return;
+        }
+        catch {
+            return;
+        }
+        const sessionId = context.sessionId;
+        if (!sessionId)
+            return;
+        const completion = settleTurn(sessionStates, sessionId);
+        if (completion) {
+            enqueueLifecycleTask(sessionId, context, () => publishCompletion(dispatcher, sessionStates, context, sessionId, completion));
+        }
+    });
+    pi.on("session_shutdown", async (event, ctx) => {
+        const context = snapshotContext(ctx);
+        const sessionId = context.sessionId;
+        if (!sessionId)
+            return;
+        const state = stateFor(sessionStates, sessionId);
+        let stopPayload;
+        if (!state.stopped) {
+            const turnId = finishTurn(sessionStates, sessionId, event);
+            stopPayload = {
+                turn_id: turnId,
+                terminationReason: firstString(objectValue(event, ["reason"])) || "session_shutdown",
+            };
+        }
+        await enqueueLifecycleTask(sessionId, context, async () => {
+            if (stopPayload)
+                await sendHook(dispatcher, "stop", context, stopPayload);
+            try {
+                await clearResumeBinding(dispatcher, context, sessionId);
+            }
+            finally {
+                releaseSessionRuntime(dispatcher, sessionStates, sessionId);
+            }
+        });
+    });
+}
+async function publishCompletion(dispatcher, sessionStates, context, sessionId, completion) {
+    const stopPayload = {
+        last_assistant_message: completion.lastAssistantMessage,
+        turn_id: completion.turnId,
+    };
+    const notificationRouted = await sendHook(dispatcher, "notification", context, {
+        message: completion.lastAssistantMessage || "Task completed",
+        turn_id: completion.turnId,
+        notification: { type: completion.notificationType },
+    });
+    if (notificationRouted)
+        stopPayload.cmux_notification_routed = true;
+    await sendHook(dispatcher, "stop", context, stopPayload);
+    const state = stateFor(sessionStates, sessionId);
+    if (!state.hasNamed) {
+        renameWorkspaceFromPrompt(dispatcher, sessionStates, context, sessionId);
+        state.hasNamed = true;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/extension/cmux/naming.d.ts

@@ -0,0 +1,5 @@
+import type { CmuxDispatcher } from "./dispatcher.js";
+import { type PiExtensionContextSnapshot, type SessionState } from "./state.js";
+export declare function titleFromPrompt(prompt: string): string | undefined;
+export declare function renameWorkspaceFromPrompt(dispatcher: CmuxDispatcher, sessionStates: Map<string, SessionState>, context: PiExtensionContextSnapshot, sessionId: string): void;
+//# sourceMappingURL=naming.d.ts.map

package/dist/extension/cmux/naming.js

@@ -0,0 +1,23 @@
+import { firstString } from "./state.js";
+export function titleFromPrompt(prompt) {
+    const words = prompt.trim().split(/\s+/).filter(Boolean);
+    if (words.length === 0)
+        return undefined;
+    return words.slice(0, 8).join(" ").slice(0, 60) || undefined;
+}
+export function renameWorkspaceFromPrompt(dispatcher, sessionStates, context, sessionId) {
+    const prompt = sessionStates.get(sessionId)?.lastPrompt;
+    if (!prompt)
+        return;
+    const title = titleFromPrompt(prompt);
+    if (!title)
+        return;
+    // Use the workspace-scoped rename form: cmux workspace rename <ws> --title <title>
+    // (NOT rename-workspace --workspace ... --surface ... which misinterprets --surface
+    // as part of the title).
+    const workspaceId = firstString(process.env.CMUX_WORKSPACE_ID);
+    if (!workspaceId)
+        return;
+    void dispatcher.run(["workspace", "rename", workspaceId, "--title", title], context.cwd, undefined, context);
+}
+//# sourceMappingURL=naming.js.map

package/dist/extension/cmux/state.d.ts

@@ -0,0 +1,33 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+export interface PendingCompletion {
+    lastAssistantMessage?: string;
+    notificationType: string;
+    turnId: string;
+}
+export interface SessionState {
+    nextTurn: number;
+    activeTurnId?: string;
+    pendingCompletion?: PendingCompletion;
+    stopped: boolean;
+    lastPrompt?: string;
+    hasNamed?: boolean;
+}
+export interface PiExtensionContextSnapshot {
+    readonly sessionId: string | null;
+    readonly cwd: string;
+    readonly notifyWarning?: () => void;
+}
+export declare function firstString(...values: unknown[]): string | null;
+export declare function objectValue(value: unknown, keys: string[]): unknown;
+export declare function textFromContent(content: unknown): string | null;
+export declare function lastAssistantMessage(event: unknown): string | undefined;
+export declare function sessionIdFrom(ctx: ExtensionContext): string | null;
+export declare function cwdFrom(ctx: ExtensionContext): string;
+export declare function snapshotContext(ctx: ExtensionContext): PiExtensionContextSnapshot;
+export declare function stateFor(sessionStates: Map<string, SessionState>, sessionId: string): SessionState;
+export declare function beginTurn(sessionStates: Map<string, SessionState>, sessionId: string, event: unknown): string;
+export declare function currentTurnId(sessionStates: Map<string, SessionState>, sessionId: string, event: unknown): string;
+export declare function finishTurn(sessionStates: Map<string, SessionState>, sessionId: string, event: unknown): string;
+export declare function settleTurn(sessionStates: Map<string, SessionState>, sessionId: string): PendingCompletion | undefined;
+export declare function warn(ctx: PiExtensionContextSnapshot | null, message: string, details?: Record<string, unknown>, notifyUser?: boolean): void;
+//# sourceMappingURL=state.d.ts.map

package/dist/extension/cmux/state.js

@@ -0,0 +1,142 @@
+export function firstString(...values) {
+    for (const value of values) {
+        if (typeof value === "string" && value.trim().length > 0)
+            return value.trim();
+    }
+    return null;
+}
+export function objectValue(value, keys) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const typed = value;
+    for (const key of keys) {
+        if (typed[key] !== undefined && typed[key] !== null)
+            return typed[key];
+    }
+    return undefined;
+}
+export function textFromContent(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return null;
+    const parts = [];
+    for (const block of content) {
+        if (!block || typeof block !== "object")
+            continue;
+        const typed = block;
+        if (typed.type === "text" && typeof typed.text === "string")
+            parts.push(typed.text);
+    }
+    return parts.join("\n") || null;
+}
+export function lastAssistantMessage(event) {
+    const messagesValue = objectValue(event, ["messages"]);
+    const messages = Array.isArray(messagesValue) ? messagesValue : [];
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (!message || typeof message !== "object")
+            continue;
+        const typed = message;
+        if (typed.role !== "assistant")
+            continue;
+        const text = firstString(textFromContent(typed.content));
+        if (text)
+            return text;
+    }
+    return undefined;
+}
+export function sessionIdFrom(ctx) {
+    try {
+        return firstString(ctx.sessionManager?.getSessionId?.());
+    }
+    catch {
+        return null;
+    }
+}
+export function cwdFrom(ctx) {
+    try {
+        return firstString(ctx.cwd, process.cwd()) || process.cwd();
+    }
+    catch {
+        return process.cwd();
+    }
+}
+export function snapshotContext(ctx) {
+    if (!ctx || typeof ctx !== "object") {
+        return { sessionId: null, cwd: process.cwd() };
+    }
+    let notifyWarning;
+    try {
+        const ui = ctx.ui;
+        if (typeof ui?.notify === "function") {
+            notifyWarning = () => ui.notify?.("cmux integration warning — check the terminal for details", "warning");
+        }
+    }
+    catch { }
+    return { sessionId: sessionIdFrom(ctx), cwd: cwdFrom(ctx), notifyWarning };
+}
+export function stateFor(sessionStates, sessionId) {
+    let state = sessionStates.get(sessionId);
+    if (!state) {
+        state = { nextTurn: 0, stopped: false };
+        sessionStates.set(sessionId, state);
+    }
+    return state;
+}
+function eventTurnId(event) {
+    return firstString(objectValue(event, ["turn_id", "turnId", "turnID"]));
+}
+export function beginTurn(sessionStates, sessionId, event) {
+    const state = stateFor(sessionStates, sessionId);
+    const turnId = eventTurnId(event) || `${sessionId}:turn-${state.nextTurn + 1}`;
+    if (!eventTurnId(event))
+        state.nextTurn += 1;
+    state.activeTurnId = turnId;
+    state.pendingCompletion = undefined;
+    state.stopped = false;
+    return turnId;
+}
+export function currentTurnId(sessionStates, sessionId, event) {
+    const state = stateFor(sessionStates, sessionId);
+    const turnId = eventTurnId(event) || state.activeTurnId || `${sessionId}:turn-${state.nextTurn + 1}`;
+    if (!eventTurnId(event) && !state.activeTurnId)
+        state.nextTurn += 1;
+    return turnId;
+}
+export function finishTurn(sessionStates, sessionId, event) {
+    const state = stateFor(sessionStates, sessionId);
+    const turnId = eventTurnId(event) || state.activeTurnId || `${sessionId}:turn-${state.nextTurn + 1}`;
+    if (!eventTurnId(event) && !state.activeTurnId)
+        state.nextTurn += 1;
+    state.activeTurnId = undefined;
+    state.pendingCompletion = undefined;
+    state.stopped = true;
+    return turnId;
+}
+export function settleTurn(sessionStates, sessionId) {
+    const state = sessionStates.get(sessionId);
+    const completion = state?.pendingCompletion;
+    if (!state || !completion || state.stopped)
+        return undefined;
+    state.activeTurnId = undefined;
+    state.pendingCompletion = undefined;
+    state.stopped = true;
+    return completion;
+}
+export function warn(ctx, message, details = {}, notifyUser = false) {
+    const payload = { source: "yagni-cmux-bridge", level: "warning", message, ...details };
+    try {
+        console.warn(JSON.stringify(payload));
+    }
+    catch {
+        console.warn(`[yagni-cmux-bridge] ${message}`);
+    }
+    if (notifyUser) {
+        try {
+            ctx?.notifyWarning?.();
+        }
+        catch { }
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/extension/config.d.ts

@@ -72,13 +72,32 @@ export interface FetchCatalogOptions {
     getToken: () => string | undefined;
     fetchImpl?: typeof fetch;
 }
+/** Guardian storage tier for this workspace (YAG-510). */
+export type GuardianStorageTier = "off" | "hash" | "raw";
+/** The startup catalog response from GET /api/yagni-code/models. */
+export interface CatalogResult {
+    models: ModelEntry[];
+    /**
+     * Per-workspace Guardian kill switch (yagni_code.guardian). Fail-safe:
+     * only an explicit `false` from the backend disables the Guardian — a
+     * missing field (older backend) reads as enabled.
+     */
+    guardianEnabled: boolean;
+    /**
+     * Guardian event storage tier (YAG-510). Polarity is deliberately the
+     * OPPOSITE of guardianEnabled: only an explicit "hash" or "raw" turns
+     * storage on — a missing field (older backend) or unknown value reads as
+     * "off" (fail toward not sending).
+     */
+    guardianStorage: GuardianStorageTier;
+}
 /**
  * Fetch the YAGNI model catalog at startup.
  *
  * @throws an actionable Error (mentioning `yagni login`) on any non-2xx
  * response so the launcher can surface a clear re-authentication prompt.
  */
-export declare function fetchCatalog(opts: FetchCatalogOptions): Promise<ModelEntry[]>;
+export declare function fetchCatalog(opts: FetchCatalogOptions): Promise<CatalogResult>;
 /** The startup company brief returned by GET /api/yagni-code/context. */
 export interface ContextBrief {
     brief: string;
@@ -156,11 +175,23 @@ export declare function isDriverCaller(env?: NodeJS.ProcessEnv): boolean;
  * sanitizing client-side is what keeps the attribution instead of losing it.
  */
 export declare function sanitizeCallerSegment(name: string, maxLength?: number): string;
+/**
+ * Attribution headers for the boot-time /context fetch. Extends
+ * {@link attributionHeaders} (session id + caller) with the surface the
+ * session is painting for (the desktop driver sets YAGNI_SURFACE=desktop;
+ * the terminal CLI sets nothing) and the shipping client version. The server
+ * uses these to emit its "YAGNI Code Session Started" analytics event —
+ * labels only on that side: a missing or malformed value can never fail the
+ * fetch, it just goes uncounted or unversioned.
+ */
+export declare function sessionTelemetryHeaders(env?: NodeJS.ProcessEnv): Record<string, string>;
 /** Options for {@link fetchContextBrief}. */
 export interface FetchContextBriefOptions {
     baseUrl: string;
     getToken: () => string | undefined;
     fetchImpl?: typeof fetch;
+    /** Env seam for the telemetry headers; defaults to process.env. */
+    env?: NodeJS.ProcessEnv;
 }
 /**
  * Fetch the workspace company brief at startup.

package/dist/extension/config.js

@@ -85,7 +85,13 @@ export async function fetchCatalog(opts) {
         throw new Error(`Failed to fetch YAGNI model catalog (HTTP ${res.status}). Run \`yagni login\` to re-authenticate.`);
     }
     const data = (await res.json());
-    return data.models;
+    return {
+        models: data.models,
+        guardianEnabled: data.guardianEnabled !== false,
+        guardianStorage: data.guardianStorage === "raw" || data.guardianStorage === "hash"
+            ? data.guardianStorage
+            : "off",
+    };
 }
 /** Shape-check for a caller label: mirrors the model proxy's own validation regex. */
 const CALLER_LABEL_RE = /^[a-z0-9][a-z0-9:_.-]{0,63}$/i;
@@ -129,8 +135,6 @@ export function attributionHeaders(env = process.env) {
         headers["x-yagni-run-id"] = runId;
     const caller = env.YAGNI_CALLER ?? "";
     headers["x-yagni-caller"] = CALLER_LABEL_RE.test(caller) ? caller : "driver";
-    if (env.YAGNI_BOOST === "1")
-        headers["x-yagni-boost"] = "1";
     return headers;
 }
 /**
@@ -173,6 +177,28 @@ export function sanitizeCallerSegment(name, maxLength = 64) {
     const trimmed = cleaned.slice(0, Math.max(0, maxLength));
     return trimmed || "agent";
 }
+/**
+ * Shape-check for a client version label (semver-ish; matches the server's
+ * own allowlist). A value that fails is dropped, never sent raw.
+ */
+const CLIENT_VERSION_RE = /^[0-9a-z][0-9a-z.+-]{0,31}$/i;
+/**
+ * Attribution headers for the boot-time /context fetch. Extends
+ * {@link attributionHeaders} (session id + caller) with the surface the
+ * session is painting for (the desktop driver sets YAGNI_SURFACE=desktop;
+ * the terminal CLI sets nothing) and the shipping client version. The server
+ * uses these to emit its "YAGNI Code Session Started" analytics event —
+ * labels only on that side: a missing or malformed value can never fail the
+ * fetch, it just goes uncounted or unversioned.
+ */
+export function sessionTelemetryHeaders(env = process.env) {
+    const headers = attributionHeaders(env);
+    headers["x-yagni-surface"] = env.YAGNI_SURFACE === "desktop" ? "desktop" : "cli";
+    const version = env.YAGNI_CODE_VERSION ?? "";
+    if (CLIENT_VERSION_RE.test(version))
+        headers["x-yagni-client-version"] = version;
+    return headers;
+}
 /**
  * Fetch the workspace company brief at startup.
  *
@@ -182,7 +208,13 @@ export function sanitizeCallerSegment(name, maxLength = 64) {
  */
 export async function fetchContextBrief(opts) {
     try {
-        const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/context`, { method: "GET", headers: { authorization: `Bearer ${opts.getToken() ?? ""}` } }, { fetchImpl: opts.fetchImpl });
+        const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/context`, {
+            method: "GET",
+            headers: {
+                authorization: `Bearer ${opts.getToken() ?? ""}`,
+                ...sessionTelemetryHeaders(opts.env),
+            },
+        }, { fetchImpl: opts.fetchImpl });
         if (!res.ok)
             return null;
         return (await res.json());