super-dsh 0.1.9 → 0.1.10

package/agent-agy-sdk/dist/index.js

@@ -0,0 +1,476 @@
+/**
+ * agent-agy-sdk provider — Google Antigravity provider plugin for DeepSeek
+ * Harness (Super D, opt-in SDK line, 2026-10-02 split).
+ *
+ * The SDK half of the Antigravity split. An `AgentFactory` that drives an
+ * `AgyBridgeClient` (the Python google-antigravity SDK bridge child —
+ * localharness materializes inside it on the FIRST prompt, so create/resume
+ * spawn nothing). Auth is consumer-first: a Gemini API key persisted in the
+ * adapter's world-home state, or ADC via the environment (the SDK picks it up;
+ * this package NEVER invokes the agy CLI — dev-rules §16a). The CLI transport
+ * is the sibling package `@pgmi-builds/agent-agy`.
+ *
+ * Session identity ("mapping only"): the DSH session id is the authority,
+ * supplied by the harness. The SDK conversation id materializes after the
+ * first turn, so the pairing is persisted in `<worldHome>/dsh-sessions.json`
+ * (agy-sessions.ts). Resume resolves that record and fails CLOSED
+ * (CONVERSATION_NOT_FOUND) when no conversation is recorded. The DSH session
+ * log is the transcript authority, written through the upstream
+ * `sessionPersistence` service (hermes create/resume transaction shape).
+ *
+ * Deployment (2026-10-02 user ruling): the composite ships this row DISABLED
+ * and the package declares NO Python dependency and no postinstall — the
+ * durable venv under the world home is fetched lazily on first real use
+ * (sdk-venv.ts).
+ */
+import { realpathSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { Service } from "@deepseek-ai/cordis";
+import { installModelSelection } from "@deepseek-ai/dsh-agent";
+import { SessionLogOffset, SessionPreparation, interruptedTurnClosers, } from "@deepseek-ai/dsh-session";
+import { AgyBridgeClient } from "./agy-client.js";
+import { registerAntigravityPreset } from "./agent-preset-agy.js";
+import { readAdapterState, writeAdapterState, readNativeDefaultModel, hasAdcEvidence, readGcloudProject } from "./agy-store.js";
+import { AgyLlmAdapter, AGY_PROVIDER_ID } from "./adapter.js";
+import { AgyAgent } from "./agent.js";
+import { sessionRecord, upsertSession } from "./agy-sessions.js";
+import { AGY_MODEL_CATALOG, parseModelId, toModelSlug } from "./models.js";
+/** Realpath of a recorded cwd, accepted only when it names an existing directory. */
+/** Extract the session-selected model id (string form) from agent options. */
+function agentOptionsModel(agentOptions) {
+    const m = agentOptions?.model;
+    return typeof m === "string" && m !== "" ? m : undefined;
+}
+function validatedCwd(cwd) {
+    if (cwd === undefined)
+        return undefined;
+    try {
+        const canonical = realpathSync(cwd);
+        return statSync(canonical).isDirectory() ? canonical : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Diagnostic trace (AGY_TRACE=1 on the dsh process enables stderr tracing). */
+const trace = (...parts) => {
+    if (process.env.AGY_TRACE === "1")
+        process.stderr.write(`[agy-sdk-provider ${Date.now() % 1_000_000}] ${parts.join(" ")}\n`);
+};
+/** Blank-session doctrine (§14 i): conversation content = turns actually ran. */
+function hasConversationContent(events) {
+    return events.some((event) => {
+        if (event.type === "turn/start" || event.type === "assistant/message")
+            return true;
+        if (event.type === "user/message") {
+            const data = event.data;
+            return data?.source?.kind === "user";
+        }
+        return false;
+    });
+}
+/** Open a read handle, pull the complete stored log, close. */
+async function readStoredEvents(persistence, id, signal) {
+    const handle = await persistence.open(id, "read", signal === undefined ? {} : { signal });
+    try {
+        return (await handle.read(0, undefined, signal === undefined ? {} : { signal })).events;
+    }
+    finally {
+        await handle.close();
+    }
+}
+export class AgyProvider extends Service {
+    static inject = ["agents", "sessions", "llm", "agentDefaultModel", "settings"];
+    /** Plain holder — prevents Cordis re-tracing the factory's ctx through a caller shadow. */
+    runtime;
+    /** The world's DSH home — anchors adapter-owned state (session map, api-key state). */
+    home;
+    opts;
+    defaultModelKey = "";
+    constructor(ctx, opts = {}) {
+        super(ctx, "agyProvider");
+        this.runtime = { ctx };
+        this.opts = opts;
+        this.home = this.resolveHome();
+        trace(`home: worldHome=${this.home}`);
+        ctx.effect(() => ctx.agents.setFactory(this), "agyProvider.setFactory()");
+        // The roster must be visible to the API gateway's root-level remote
+        // enumeration; register it on this plugin's own (top-level) fiber.
+        // 0.1.7: roster/selection/document RPC + the `agentPreset` session
+        // projection all live in the host AgentPresetRegistry (mounted by the
+        // dsh-web-app bundle's `agent-preset-registry` row; the adapter patch
+        // pins its `default` to the Antigravity preset). The adapter only registers
+        // its one fixed preset into the registry.
+        registerAntigravityPreset(ctx);
+        this.registerModelCatalog();
+        this.registerDefaultModel();
+    }
+    /** The world's DSH home: boot-provided dshHomePath first, env last. */
+    resolveHome() {
+        const fromBoot = this.runtime.ctx.get("dshHomePath");
+        if (typeof fromBoot === "string" && fromBoot !== "")
+            return fromBoot;
+        if (typeof fromBoot === "function") {
+            const resolved = fromBoot();
+            if (typeof resolved === "string" && resolved !== "")
+                return resolved;
+        }
+        return process.env.DSH_HOME ?? join(process.cwd(), ".tests", "superd");
+    }
+    /** Effective Gemini API key: adapter state first, then the environment. */
+    resolveApiKey() {
+        const state = readAdapterState(this.home);
+        if (typeof state.apiKey === "string" && state.apiKey !== "")
+            return state.apiKey;
+        const env = process.env.GEMINI_API_KEY;
+        return typeof env === "string" && env !== "" ? env : undefined;
+    }
+    /**
+     * Auth evidence for the §17 onboarding gate: an API key (state or env) OR
+     * ADC evidence is enough — the SDK consumes either transparently, so a user
+     * with gcloud ADC must NOT be pushed into key onboarding.
+     */
+    hasAuthEvidence() {
+        if (this.resolveApiKey() !== undefined)
+            return true;
+        return hasAdcEvidence(process.env, process.env.HOME ?? "");
+    }
+    /** Default model id: adapter state → native TUI default (slug-normalized) → catalog head. */
+    resolveDefaultModelId() {
+        const state = readAdapterState(this.home);
+        if (typeof state.defaultModel === "string" && parseModelId(state.defaultModel) !== undefined)
+            return state.defaultModel;
+        const native = readNativeDefaultModel(this.opts.nativeHome ?? join(process.env.HOME ?? "", ".gemini"));
+        const slug = toModelSlug(native);
+        if (slug !== undefined)
+            return slug;
+        return AGY_MODEL_CATALOG[0].slug;
+    }
+    /** Legacy slug-only default (default-model push keeps slug form). */
+    resolveDefaultModel() {
+        const state = readAdapterState(this.home);
+        if (typeof state.defaultModel === "string" && state.defaultModel !== "")
+            return state.defaultModel;
+        const native = readNativeDefaultModel(this.opts.nativeHome ?? join(process.env.HOME ?? "", ".gemini"));
+        const slug = toModelSlug(native);
+        if (slug !== undefined)
+            return slug;
+        return AGY_MODEL_CATALOG[0].slug;
+    }
+    /** Static route: provider `agy` + the resolved default (or the explicit ask).
+     *  The selected model id (`slug` or `slug@level`) rides in `options.model`
+     *  so clientOptions can forward slug+thinkingLevel to the bridge start frame. */
+    sessionAgentOptions(requested) {
+        const requestedModel = typeof requested?.model === "string" ? requested.model : undefined;
+        const explicit = requestedModel !== undefined && parseModelId(requestedModel) !== undefined
+            ? requestedModel
+            : undefined;
+        const model = explicit ?? this.resolveDefaultModelId();
+        return { ...(requested ?? {}), provider: AGY_PROVIDER_ID, model };
+    }
+    requirePersistence(op) {
+        const persistence = this.runtime.ctx.get("sessionPersistence");
+        if (persistence === undefined) {
+            throw new Error(`cannot ${op} an Agy session: session persistence is not configured`);
+        }
+        return persistence;
+    }
+    agentRuntime(cwd) {
+        const provider = this;
+        return {
+            session: { cwd },
+            awaitingKey: !provider.hasAuthEvidence(),
+            onSaveApiKey: (key) => {
+                writeAdapterState(provider.home, { ...readAdapterState(provider.home), apiKey: key });
+                trace("onboarding: api key persisted to adapter state (world home)");
+            },
+            onTurnDone: undefined, // replaced per-session by followConversationId below
+        };
+    }
+    /** Persist the Dash↔conversation pairing once the first turn materializes it. */
+    followConversationId = (id, client) => {
+        const cid = client.conversationId;
+        if (cid === "")
+            return;
+        try {
+            upsertSession(this.home, String(id), { conversationId: cid });
+            trace(`conversation id recorded for ${String(id)}: ${cid}`);
+        }
+        catch (error) {
+            this.runtime.ctx.logger.warn(`agy-sdk-provider: failed to persist the conversation id for ${String(id)}: ${String(error)}`);
+        }
+    };
+    registerModelCatalog() {
+        const llm = this.runtime.ctx.get("llm");
+        if (llm === undefined)
+            return;
+        llm.registerAdapter([AGY_PROVIDER_ID], new AgyLlmAdapter());
+    }
+    /** Push the resolved default model into the world's `agentDefaultModel`. */
+    registerDefaultModel() {
+        this.runtime.ctx.inject(["agentDefaultModel", "settings"], (mCtx) => {
+            const service = mCtx.get("agentDefaultModel");
+            if (service === undefined)
+                return;
+            const target = { provider: AGY_PROVIDER_ID, model: this.resolveDefaultModel() };
+            const targetKey = `${target.provider}/${target.model}`;
+            const current = service.currentSelection?.();
+            const currentKey = current === undefined ? undefined : `${current.provider}/${current.model}`;
+            if (currentKey === targetKey || currentKey === this.defaultModelKey)
+                return;
+            trace(`default model: ${currentKey ?? "none"} → ${targetKey}`);
+            const settings = mCtx.get("settings");
+            void Promise.resolve(settings?.replace?.("agent-default-model", target))
+                .then(() => service.saveSelection?.(target))
+                .then(() => {
+                this.defaultModelKey = targetKey;
+                this.runtime.ctx.logger.info(`agy-sdk-provider: default model ← static catalog / native settings: ${targetKey}`);
+            })
+                .catch((error) => {
+                this.runtime.ctx.logger.warn(`agy-sdk-provider: default model save failed: ${String(error)}`);
+            });
+        });
+    }
+    async createAgent(ownerCtx, options) {
+        const loopCtx = this.runtime.ctx;
+        const id = options.sessionId;
+        const meta = options.meta ?? {};
+        const cwd = meta.cwd;
+        if (meta.parentSession !== undefined) {
+            throw new Error(`cannot fork session "${meta.parentSession}" onto the Agy provider: Antigravity has no native session fork`);
+        }
+        const persistence = this.requirePersistence("create");
+        const spawnCwd = validatedCwd(cwd) ?? process.cwd();
+        trace(`create id=${id} spawnCwd=${spawnCwd}`);
+        // Full-lazy (§14-i): construct the client (spawns NOTHING); the bridge
+        // child materializes on the first real prompt.
+        const client = this.createLiveClient(spawnCwd, agentOptionsModel(options.agentOptions), options.agentOptions?.reasoningEffort);
+        const preparation = SessionPreparation.create(loopCtx.sessions.prepare(id, {
+            ...(options.seed === undefined ? {} : { seed: options.seed }),
+            ...(meta === undefined ? {} : { meta }),
+            ...(options.inheritedEventCount === undefined ? {} : { inheritedEventCount: options.inheritedEventCount }),
+        }));
+        let stored;
+        let handedOff = false;
+        try {
+            stored = await this.createStoredSession(persistence, preparation.session, options.signal);
+            upsertSession(this.home, String(id), { conversationId: null, cwd: spawnCwd, createdAt: Date.now(), preset: null });
+            handedOff = true;
+            const agentOptions = await this.sessionAgentOptions(options.agentOptions);
+            return await setupAndPublish(loopCtx, ownerCtx, id, agentOptions, options.setup, preparation.session, client, options.parentAgent, "startup", { enterSession: true, preparation }, stored, this.agentRuntime(spawnCwd), () => this.followConversationId(id, client));
+        }
+        catch (error) {
+            trace(`create ${id} THREW: ${String(error)}`);
+            void client.close();
+            if (!handedOff)
+                await stored?.handle.close().catch(() => { });
+            throw error;
+        }
+        finally {
+            if (!handedOff)
+                preparation[Symbol.dispose]();
+        }
+    }
+    async resume(ownerCtx, options) {
+        const loopCtx = this.runtime.ctx;
+        const id = options.resumeSessionId;
+        // Identity ("mapping only") with BLANK-SESSION TOLERANCE (2026-09-18,
+        // dev-rules §14 i — pi doctrine mirror): the Dash host eagerly resumes on
+        // view/model-change, so a never-materialized session (no record, or a
+        // record whose native conversation never produced a turn) resumes AS
+        // FRESH — zero processes until the first prompt. A MISSING record with
+        // conversation-bearing DSH log content stays a genuine orphan → fail loud.
+        const record = sessionRecord(this.home, String(id));
+        const blank = record === undefined || record.conversationId === null || record.conversationId === "";
+        trace(`resume id=${id} record=${record === undefined ? "MISSING" : record.conversationId ?? "NO-CONVERSATION"}${blank ? " (blank-tolerant)" : ""}`);
+        const persistence = this.requirePersistence("resume");
+        let orphanCheck;
+        if (record === undefined) {
+            orphanCheck = await readStoredEvents(persistence, id, options.signal);
+            if (hasConversationContent(orphanCheck)) {
+                const error = new Error(`cannot resume session "${id}": no Antigravity conversation is recorded for this Dash session id — start a new session`);
+                error.code = "CONVERSATION_NOT_FOUND";
+                throw error;
+            }
+        }
+        const spawnCwd = blank
+            ? (record !== undefined ? validatedCwd(record.cwd) ?? process.cwd() : process.cwd())
+            : (() => {
+                const verified = validatedCwd(record.cwd);
+                if (verified === undefined) {
+                    throw new Error(`cannot resume session "${id}": its recorded working directory no longer exists`);
+                }
+                return verified;
+            })();
+        const client = this.createLiveClient(spawnCwd, agentOptionsModel(options.agentOptions), options.agentOptions?.reasoningEffort);
+        let handle;
+        let stored;
+        let preparation;
+        let handedOff = false;
+        try {
+            handle = await persistence.open(id, "write", options.signal === undefined ? {} : { signal: options.signal });
+            const cold = await handle.read(0, undefined, options.signal === undefined ? {} : { signal: options.signal });
+            const closers = interruptedTurnClosers(cold.events);
+            if (closers.length > 0)
+                await handle.append(closers);
+            preparation = SessionPreparation.create(loopCtx.sessions.prepare(id, {
+                seed: [...cold.events, ...closers],
+                meta: structuredClone(handle.header),
+                inheritedEventCount: handle.inheritedEventCount,
+                eventState: cold.eventState,
+            }));
+            stored = { handle, storedCount: cold.events.length + closers.length };
+            trace(`resume id=${id} seeded ${cold.events.length} events (+${closers.length} closers)`);
+            handle = undefined;
+            handedOff = true;
+            const agentOptions = await this.sessionAgentOptions(options.agentOptions);
+            return await setupAndPublish(loopCtx, ownerCtx, id, agentOptions, options.setup, preparation.session, client, options.parentAgent, "resume", { enterSession: true, preparation }, stored, this.agentRuntime(spawnCwd), () => this.followConversationId(id, client));
+        }
+        catch (error) {
+            trace(`resume ${id} THREW: ${String(error)}`);
+            void client.close();
+            if (!handedOff)
+                await handle?.close().catch(() => { });
+            throw error;
+        }
+        finally {
+            if (!handedOff)
+                preparation?.[Symbol.dispose]();
+        }
+    }
+    /**
+       * Live transport: SDK-ONLY (2026-10-02 user ruling).
+       *
+       * This package is the opt-in SDK half of the Antigravity split: it drives the
+       * Python google-antigravity SDK through the JSONL bridge and NEVER invokes the
+       * user's `agy` CLI (that transport is `@pgmi-builds/agent-agy`).
+       * Auth (§16a transparency): a key from adapter state / `GEMINI_API_KEY` rides
+       * the start frame; without one the SDK falls back to ADC (Vertex, project read
+       * from the gcloud default). Neither ⇒ the §17 onboarding branch answers the
+       * first turn locally, before anything spawns.
+       */
+    createLiveClient(cwd, modelId, reasoningEffort) {
+        return new AgyBridgeClient(this.clientOptions(cwd, modelId, reasoningEffort));
+    }
+    /** Bridge child options: world cwd + overrides; the api key rides the start config. */
+    clientOptions(cwd, modelId, reasoningEffort) {
+        // Auth plane (§16a): API key when present; otherwise the SDK's Vertex
+        // endpoint over ADC — which needs an explicit project, read from the
+        // gcloud CLI default. Without either, sessions gate into §17 onboarding.
+        const apiKey = this.resolveApiKey();
+        let project = this.opts.project;
+        let location = this.opts.location;
+        if (apiKey === undefined && project === undefined && hasAdcEvidence(process.env, process.env.HOME ?? "")) {
+            project = readGcloudProject(process.env.HOME ?? "");
+            location = location ?? "global";
+        }
+        // Session-selected model id wins over the provider default (previously a
+        // split-brain: the session showed one model, the bridge started another).
+        // `slug@level` decodes into model + thinking_level for the start frame.
+        const parsed = parseModelId(modelId ?? this.resolveDefaultModelId());
+        return {
+            apiKey,
+            project,
+            location,
+            model: parsed?.slug ?? this.resolveDefaultModelId(),
+            // TUI parity: the native default ships (Medium); without an explicit
+            // level the bridge sends none and thinking blocks rarely stream.
+            thinkingLevel: parsed?.thinkingLevel ?? "medium",
+            approvalMode: this.opts.approvalMode ?? "allow",
+            workspaces: [cwd],
+            bridgePath: this.opts.bridgePath,
+            pythonBin: this.opts.pythonBin,
+            spawnAttempts: this.opts.spawnAttempts,
+            // Anchors the durable SDK venv: per-world, writable, survives restarts.
+            worldHome: this.home,
+        };
+    }
+    async createStoredSession(persistence, session, signal) {
+        const handle = await persistence.create(session.header, {
+            inheritedEventCount: session.inheritedEventCount,
+            ...(signal === undefined ? {} : { signal }),
+        });
+        return { handle, storedCount: 0 };
+    }
+}
+/** Durable flush of the session's pre-publication suffix. */
+async function appendUnstoredSuffix(stored, session) {
+    const suffix = session.snapshotEvents(SessionLogOffset(stored.storedCount));
+    if (suffix.length > 0)
+        await stored.handle.append(suffix);
+    stored.storedCount += suffix.length;
+}
+/** Shared create/resume transaction (module-level: Cordis tracing proxy). */
+async function setupAndPublish(loopCtx, ownerCtx, id, agentOptions, setup, session, client, parentAgent, source, opts, stored, runtimeInfo, onTurnDone) {
+    const runtime = { ...runtimeInfo, onTurnDone };
+    let detachSession;
+    let detachAgent;
+    let agent;
+    let idleExit;
+    try {
+        agent = new AgyAgent(loopCtx, id, agentOptions, session, client, () => idleExit?.(), runtime);
+        // Pin THIS session to the agy route (static resolution — synchronous).
+        try {
+            const selection = { provider: agentOptions.provider ?? "agy", model: agentOptions.model ?? "" };
+            if (selection.model !== "") {
+                let picked = selection;
+                installModelSelection(agent.ctx, {
+                    get current() { return picked; },
+                    set current(next) { picked = next; },
+                    assembled: undefined,
+                });
+                session.append("model/selection", selection);
+                trace(`session route pinned: ${selection.provider}/${selection.model}`);
+            }
+        }
+        catch (error) {
+            trace(`session route pin failed: ${String(error)}`);
+        }
+        const commit = await setup?.(agent.ctx, agent);
+        commit?.commit();
+        await appendUnstoredSuffix(stored, session);
+        if (opts.enterSession) {
+            detachSession = agent.ctx.sessions.enter(session);
+            agent.ctx.sessions.announce(session);
+        }
+        detachAgent = loopCtx.agents.enter(agent, parentAgent);
+        // 0.1.6: announce(agent, source) is required, async, and emits agent/created
+        // itself — the manual agent/session-start emission is gone upstream.
+        await loopCtx.agents.announce(agent, source);
+        let disposed = false;
+        let unfollowOwner;
+        const dispose = async () => {
+            if (disposed)
+                return;
+            disposed = true;
+            unfollowOwner?.();
+            await agent?.dispose();
+            detachAgent?.();
+            detachSession?.();
+            await stored.handle.close();
+        };
+        idleExit = () => {
+            void dispose().catch((error) => {
+                loopCtx.logger.warn(`agy-sdk-provider: teardown of ${id} failed: ${String(error)}`);
+            });
+        };
+        unfollowOwner = ownerCtx.effect(() => () => {
+            void dispose().catch((error) => {
+                loopCtx.logger.warn(`agy-sdk-provider: owner-unload teardown of ${id} failed: ${String(error)}`);
+            });
+        }, `agyProvider.lifecycle(${id})`);
+        return { agent, dispose };
+    }
+    catch (error) {
+        trace(`setupAndPublish ${id} FAILED: ${String(error)}`);
+        detachAgent?.();
+        detachSession?.();
+        void agent?.dispose().catch(() => { });
+        void client.close();
+        throw error;
+    }
+    finally {
+        opts.preparation?.[Symbol.dispose]();
+    }
+}
+export default AgyProvider;

package/agent-agy-sdk/dist/models.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Static model catalog for the Gemini consumer surface. The google-antigravity
+ * SDK has no model-list API and the CLI catalog path is auth-gated, so the
+ * catalog is static AND endpoint-verified (2026-09-18 probes on both auth
+ * planes; non-listed slugs 404 / are retired).
+ *
+ * Model ids are PLAIN slugs — thinking effort is a per-route option surfaced
+ * through the adapter's reasoning metadata (WebUI Effort selector →
+ * AgentOptions.reasoningEffort), NOT extra catalog entries (user ruling
+ * 2026-09-18).
+ */
+export interface AgyCatalogModel {
+    slug: string;
+    label: string;
+    /** Effort levels the CLI/SDK accept for this slug (absent = no effort param). */
+    efforts?: readonly string[];
+    defaultEffort?: string;
+}
+export declare const AGY_MODEL_CATALOG: readonly AgyCatalogModel[];
+/** Selectable model ids (plain slugs). */
+export declare function modelIds(): string[];
+export declare function catalogSlugs(): string[];
+/** Parse a selectable model id: plain slug, or legacy `slug@level`. */
+export declare function parseModelId(id: string | undefined): {
+    slug: string;
+    thinkingLevel?: string;
+} | undefined;
+/** Efforts for a slug (undefined = the slug takes no effort parameter). */
+export declare function effortsFor(slug: string): readonly string[] | undefined;
+export declare function defaultEffortFor(slug: string): string | undefined;
+/** Cheapest live pair on the CLI key path (probed 2026-09-18). CLI default. */
+export declare const CLI_DEFAULT_MODEL: {
+    slug: string;
+    thinkingLevel: string;
+};
+/**
+ * Normalize a model reference to an SDK-facing slug. The native TUI settings
+ * store display names ("Gemini 3.7 Flash (Medium)"); slugs pass through;
+ * unknown display names → undefined (caller uses the catalog head).
+ */
+export declare function toModelSlug(model: string | undefined): string | undefined;

package/agent-agy-sdk/dist/models.js

@@ -0,0 +1,74 @@
+/**
+ * Static model catalog for the Gemini consumer surface. The google-antigravity
+ * SDK has no model-list API and the CLI catalog path is auth-gated, so the
+ * catalog is static AND endpoint-verified (2026-09-18 probes on both auth
+ * planes; non-listed slugs 404 / are retired).
+ *
+ * Model ids are PLAIN slugs — thinking effort is a per-route option surfaced
+ * through the adapter's reasoning metadata (WebUI Effort selector →
+ * AgentOptions.reasoningEffort), NOT extra catalog entries (user ruling
+ * 2026-09-18).
+ */
+export const AGY_MODEL_CATALOG = [
+    { slug: "gemini-3.7-flash", label: "Gemini 3.7 Flash", efforts: ["low", "medium", "high"], defaultEffort: "medium" },
+    { slug: "gemini-3.6-flash", label: "Gemini 3.6 Flash", efforts: ["low", "medium", "high"], defaultEffort: "low" },
+    { slug: "gemini-3.5-flash", label: "Gemini 3.5 Flash", efforts: ["low", "medium", "high"], defaultEffort: "medium" },
+    { slug: "gemini-2.5-pro", label: "Gemini 2.5 Pro" },
+    { slug: "gemini-2.5-flash", label: "Gemini 2.5 Flash" },
+];
+/** Selectable model ids (plain slugs). */
+export function modelIds() {
+    return AGY_MODEL_CATALOG.map((m) => m.slug);
+}
+export function catalogSlugs() {
+    return modelIds();
+}
+/** Parse a selectable model id: plain slug, or legacy `slug@level`. */
+export function parseModelId(id) {
+    if (id === undefined)
+        return undefined;
+    const at = id.indexOf("@");
+    const slug = at < 0 ? id : id.slice(0, at);
+    if (!catalogSlugs().includes(slug))
+        return undefined;
+    if (at < 0)
+        return { slug };
+    const level = id.slice(at + 1);
+    const entry = AGY_MODEL_CATALOG.find((m) => m.slug === slug);
+    if (entry?.efforts && entry.efforts.includes(level))
+        return { slug, thinkingLevel: level };
+    return { slug };
+}
+/** Efforts for a slug (undefined = the slug takes no effort parameter). */
+export function effortsFor(slug) {
+    return AGY_MODEL_CATALOG.find((m) => m.slug === slug)?.efforts;
+}
+export function defaultEffortFor(slug) {
+    return AGY_MODEL_CATALOG.find((m) => m.slug === slug)?.defaultEffort;
+}
+/** Cheapest live pair on the CLI key path (probed 2026-09-18). CLI default. */
+export const CLI_DEFAULT_MODEL = {
+    slug: "gemini-3.6-flash",
+    thinkingLevel: "low",
+};
+/**
+ * Normalize a model reference to an SDK-facing slug. The native TUI settings
+ * store display names ("Gemini 3.7 Flash (Medium)"); slugs pass through;
+ * unknown display names → undefined (caller uses the catalog head).
+ */
+export function toModelSlug(model) {
+    if (!model)
+        return undefined;
+    const v = model.trim();
+    if (!v)
+        return undefined;
+    if (/^[a-z0-9.-]+$/.test(v) && !v.includes(" "))
+        return v;
+    const base = v.replace(/\s*\([^)]*\)\s*$/, "").trim().toLowerCase();
+    const slug = base.replace(/\s+/g, "-");
+    if (catalogSlugs().includes(slug))
+        return slug;
+    if (/^gemini-[0-9]/.test(slug))
+        return slug;
+    return undefined;
+}

package/agent-agy-sdk/dist/sdk-venv.d.ts

@@ -0,0 +1,76 @@
+/**
+ * sdk-venv.ts — the lazy, durable Python venv the SDK bridge runs on.
+ *
+ * 2026-10-02 user ruling (spec §4.2): this package declares NO Python
+ * dependency and ships NO postinstall/allow-scripts hook. Nothing is fetched at
+ * install time; the FIRST real use fetches the venv into the world home, where
+ * it is durable across sessions, restarts and package upgrades. A second use
+ * reuses it (idempotent), and a FAILED fetch leaves a trace on disk instead of
+ * silently degrading into a confusing bridge crash.
+ *
+ * Why the world home rather than the package root: the package root is the
+ * installed tarball — read-only in every real consumer install, and shared by
+ * every world (the CLI one included). The world home is per-runtime, writable,
+ * and already the home of this adapter's own state.
+ *
+ * The bootstrap is two idempotent steps, so a half-built venv heals in place
+ * rather than being thrown away and re-downloaded:
+ *   1. `<worldHome>/sdk-venv/bin/python` missing → `python3 -m venv <dir>`
+ *   2. `<worldHome>/sdk-venv.json` marker missing → `pip install google-antigravity`
+ */
+/** The Python distribution the bridge imports (`bridge/agy_bridge.py`). */
+export declare const SDK_PYTHON_PACKAGE = "google-antigravity";
+/** Layout of the durable venv inside a world home. */
+export interface SdkVenvLayout {
+    /** The venv root. */
+    dir: string;
+    /** The interpreter the bridge is spawned with. */
+    python: string;
+    /** Used for the (idempotent) install step. */
+    pip: string;
+    /** Written last; its presence means the venv is complete. */
+    marker: string;
+    /** Failure trace — only ever written by a failed fetch. */
+    errorLog: string;
+    /** Bootstrap lock directory (mkdir is atomic on POSIX). */
+    lock: string;
+}
+export declare function sdkVenvLayout(worldHome: string): SdkVenvLayout;
+export interface SdkVenvRecord {
+    /** Installed distribution name. */
+    package: string;
+    /** Interpreter path (absolute) at install time. */
+    python: string;
+    /** ISO timestamp of the successful fetch. */
+    installedAt: string;
+    /** Interpreter used to create the venv. */
+    createdWith: string;
+}
+/** Read the install marker; undefined when absent or unreadable. */
+export declare function readSdkVenvRecord(worldHome: string): SdkVenvRecord | undefined;
+/** Fast path: the complete venv already exists → the interpreter to use. */
+export declare function resolveSdkPython(worldHome: string): string | undefined;
+export interface EnsureSdkVenvOptions {
+    /** Interpreter used to CREATE the venv (default `python3`). */
+    basePython?: string;
+    /** Command runner (tests inject a fake; default is a synchronous exec). */
+    run?: (cmd: string, args: string[]) => void;
+    trace?: (...parts: unknown[]) => void;
+    /** How long to wait for another process's bootstrap before giving up (ms). */
+    lockTimeoutMs?: number;
+    /** Poll interval while another process holds the lock (ms). */
+    lockPollMs?: number;
+    /** Lock older than this is treated as abandoned and stolen (ms). */
+    lockStaleMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Return the interpreter path for `<worldHome>`'s durable venv, fetching it
+ * first when it is absent or incomplete.
+ *
+ * Idempotent: a complete venv short-circuits without touching the network.
+ * Failures append to `<worldHome>/sdk-venv.error.log` and throw a single
+ * actionable error — never a partial venv left behind a success marker.
+ */
+export declare function ensureSdkVenv(worldHome: string, opts?: EnsureSdkVenvOptions): Promise<string>;