super-dsh 0.1.9 → 0.1.10-e

package/README.md

@@ -18,21 +18,43 @@ dsh plugin --profile <name> add super-dsh@0.1.0
 ```
 
 That single package composes the whole line (`@pgmi-builds/superd-hub` plus the
-six `@pgmi-builds/agent-*` packages). Restart the profile and the
-sidebar gains the runtime selector; each world provisions its own nested DSH
+six primary `@pgmi-builds/agent-*` packages and three OPTIONAL SDK halves).
+Restart the profile and the
 home under `<DSH_HOME>/agents/<label>/` on first boot.
 
 ## Runtimes
 
 | Label | Runtime | Integration |
 |---|---|---|
-| OMP | OMP (`~/.omp`) | in-process SDK sidecar, lazy per session |
+| OMP | OMP (`~/.omp`) | host `omp` binary over RPC (`omp --mode rpc`, NDJSON v1), lazy per session |
 | Codex | Codex CLI (`~/.codex`) | adapter world plugin |
 | Claude | Claude Code (`~/.claude`) | standalone adapter, joined by the hub |
 | Pi | pi coding agent (`~/.pi`) | in-process SDK |
 | Hermes | Hermes (`~/.hermes`) | gateway child |
 | Antigravity | agy SDK | Python bridge (`bridge/agy_bridge.py`) |
 
+### Opt-in SDK halves
+
+Three runtimes also ship a preserved in-process SDK transport beside the primary
+line: `agent-omp-sdk`, `agent-agy-sdk` and `agent-codex-sdk`. Each is a complete
+standalone copy of its adapter with an injectable transport, and each
+
+- is **`disabled: true`** in this package's composite patch — turning the row on
+  IS the switch (`plugin-presence IS the roster`), and it runs under its own
+  world key (`omp-sdk` / `agy-sdk` / `codex-sdk`) so it can sit beside the
+  primary row without a duplicate-key error;
+- declares **no dependency at all** — not a dependency, not an optional, not a
+  peer — so `dsh plugin add super-dsh` installs and downloads nothing for it,
+  and ships no postinstall;
+- supports the same multi-provider surface as its primary line (the Codex halves
+  share one provider store implementation, one native-config reader, one route
+  resolver and one `codexProviders` panel; only the launch encoding differs —
+  argv for the app-server child, a config object for the SDK);
+- fetches its own durable runtime into `<DSH_HOME>/agents/<key>/` on the FIRST
+  real prompt (bun + the coding-agent tree for OMP, a Python venv for agy, the
+  `@openai/codex-sdk` tree for Codex), where it survives restarts and upgrades.
+  Pre-warm with `npm run fetch-sdk-runtime` in the package.
+
 ## Design
 
 - **S1** selector handoff is one hop; the dispatcher never addresses sessions.

package/agent-agy/cordis.patch.yml

@@ -1,11 +1,14 @@
-# @pgmi-builds/agent-agy bundle patch (AW-G SDK line, pi/hermes form).
+# @pgmi-builds/agent-agy bundle patch (pi/hermes form).
 # The `dsh.bundle.patch` layer of the adapter package: mounts the agy provider
 # and disables the native components it replaces. Port/webserver posture is
 # NOT here (worldMountPatches owns it); the world profile patch pins the home.
 #
-# Auth (2026-09-18 consumer-first ruling, dev-rules §16a): Gemini API key in
-# adapter world-home state (or GEMINI_API_KEY env), else ADC — the SDK consumes
-# either transparently. The agy CLI is never invoked.
+# Auth (2026-10-02 ruling 「拥抱用户自己的使用环境」): the adapter drives the
+# user's OWN Antigravity CLI and shares their real native configuration —
+# settings.json, ADC, keyring. Ladder: Gemini API key → OAuth (placeholder) →
+# ADC. The opt-in Python SDK transport is the sibling package
+# @pgmi-builds/agent-agy-sdk (its own bundle, delivered disabled).
+
 
 - insert:
     - id: agy-provider

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

@@ -1,26 +1,27 @@
 /**
- * AgyAgent — the Dash `Agent` shim over one `AgyBridgeClient` (the Python SDK
- * bridge child; localharness materializes inside it on the first prompt).
+ * AgyAgent — the Dash `Agent` shim over one `AgyCliClient` (the user's own
+ * Antigravity CLI in headless stream-json mode; the child spawns lazily on the
+ * first real prompt).
  *
- * Projection (bridge → Dash session events):
+ * Projection (CLI stream → Dash session events):
  *   (prompt delivery)   → turn/start + user/message
  *   chunk (streamed)    → assistant stream frames (v2 protocol) accumulated
  *                         as durable records; the FULL text commits once as
  *                         assistant/message at `done`
- *   tool                → (V1: bridge supplies name only — omitted from the
+ *   tool                → (V1: CLI supplies name only — omitted from the
  *                         log rather than fabricated; event-stream honesty)
  *   done                → assistant/message + step/end + turn/end {completed}
  *   error               → turn/end {error} with a stable code
  *
- * Bridge gaps registered explicitly (never fabricated):
- * - token usage: the bridge `done` event carries none → no usage field.
+ * CLI-stream gaps registered explicitly (never fabricated):
+ * - token usage: the CLI `done` event carries none → no usage field.
  * - tool fidelity: only a tool name arrives (no call id / args / result) → no
  *   tool/call or tool/result events in V1.
- * - steer/cancel: the bridge has no in-turn interrupt; `steer` degrades to a
+ * - steer/cancel: the CLI has no in-turn interrupt; `steer` degrades to a
  *   parked follow-up, `cancel` records the cause (applied at the terminal).
  *
  * Onboarding (§17 minimal, consumer-first): when no Gemini API key is known,
- * the first user turn never touches the bridge — the turn is answered locally
+ * the first user turn never touches the CLI — the turn is answered locally
  * with a system/message asking for the key; a pasted key is persisted through
  * `onApiKey` (adapter state, world home only) and confirmed in the same turn.
  */
@@ -29,10 +30,10 @@ import type { Agent, AgentOptions, AgentStatus, CancelOptions, InboxTarget } fro
 import { Inbox } from "./inbox.js";
 import type { AgentCancelCause, Session, SessionId, UserMessage } from "@deepseek-ai/dsh-session";
 import type { TokenUsage } from "@deepseek-ai/dsh-llm";
-import type { AgyBridgeClient } from "./agy-client.js";
+import type { AgyCliClient } from "./agy-cli-client.js";
 import { type WithSystemHead } from "../../superd-hub/dist/index.js";
-/** Structural union of the two live transports (SDK bridge | CLI stream). */
-export type LiveAgyClient = Pick<AgyBridgeClient, "conversationId" | "lastUsage" | "onThinkingDelta" | "onToolEvent" | "setApprovalHandler" | "turn" | "close"> & {
+/** The CLI stream transport the agent drives (SDK bridge moved to agent-agy-sdk). */
+export type LiveAgyClient = Pick<AgyCliClient, "conversationId" | "lastUsage" | "onThinkingDelta" | "onToolEvent" | "setApprovalHandler" | "turn" | "close"> & {
     setSystemMessageHandler?(handler: (text: string) => void): void;
 };
 /** Classify a bridge turn failure into the stable {message, code} UI chip. */

package/agent-agy/dist/agy-auth-gateway.d.ts

@@ -0,0 +1,124 @@
+/**
+ * agy-auth-gateway.ts — the adapter-owned Remote behind the Hub's Antigravity
+ * settings panel (P3, 2026-10-02 user ruling).
+ *
+ * Why a Remote and not a hub route: the auth ladder, the probe results and the
+ * native-settings mutation are ADAPTER config (agent-adapter-dev-rules §12), so
+ * the adapter owns them and the hub only forwards. `TypertRemoteService` +
+ * `@Remote` is the whole mechanism — standard (TC39) method decorators recorded
+ * on the class prototype, read back at dispatch time by the gateway's
+ * source-claim scan. There is NO codegen step and no compiler-injected
+ * metadata, which is why a plain `tsc` adapter build can ship one.
+ *
+ * Wire contract (both halves are pinned by tests):
+ *   request   POST /hub/api?agent=agy
+ *             { type:'client-request', rpcId, method:'agyAuth/get'|'agyAuth/set',
+ *               payload: { args: { request?: AgyAuthSetRequest } } }
+ *   response  { type:'server-response', rpcId, result:{ ok:true, value:<view> } }
+ *
+ * The endpoint namespace is `agyAuth`; the hub's carrier forwards
+ * `envelope.method` verbatim to this world's `typertGateway`.
+ *
+ * Side effects are deliberate and bounded (the 2026-10-02 ruling
+ * 「拥抱用户自己的使用环境」): choosing a form rewrites the USER's real
+ * `~/.gemini/antigravity-cli/settings.json` immediately, so their own TUI
+ * behaves the same way afterwards. The SELECTION itself lives in the world home
+ * (`agy-adapter.json`) — adapter state never leaks into the native home.
+ *
+ * @module agent-agy/agy-auth-gateway
+ */
+import type { Context } from "@deepseek-ai/cordis";
+import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+import { type AgyAuthAvailability, type AgyAuthMode } from "./agy-auth.js";
+/** One auth option as the Hub panel renders it (`client/agent-settings.ts` parses this). */
+export interface AgyAuthOptionView {
+    /** Stable id the panel round-trips (`apiKey` | `oauth` | `adc`). */
+    readonly key: AgyAuthMode;
+    readonly label: string;
+    /** Detected on THIS machine right now. */
+    readonly available: boolean;
+    /** Rendered but never selectable this round (OAuth). */
+    readonly placeholder: boolean;
+    readonly hint: string;
+}
+/** The panel's full state: the options, the choice, and what would actually run. */
+export interface AgyAuthView {
+    readonly methods: readonly AgyAuthOptionView[];
+    /** The user's persisted choice; `null` when they have not made one. */
+    readonly selected: AgyAuthMode | null;
+    /** What a new session would use right now (ladder applied); `null` when nothing is available. */
+    readonly effective: AgyAuthMode | null;
+    /** The native file a selection rewrites — shown so the effect is never a surprise. */
+    readonly settingsPath: string;
+    /** Populated only when something needs explaining (stale choice, absent ADC). */
+    readonly note?: string;
+}
+/** `agyAuth/set` payload (the gateway's single wire argument). */
+export interface AgyAuthSetRequest {
+    /**
+     * The form to adopt. `null` clears the explicit choice and hands the decision
+     * back to the ladder. Unknown values are rejected, never coerced.
+     */
+    readonly mode?: AgyAuthMode | null;
+}
+/**
+ * The adapter's auth-form Remote. One instance per world context.
+ */
+export declare class AgyAuthGateway extends TypertRemoteService {
+    private readonly home;
+    private readonly realHome;
+    private readonly availability;
+    /**
+     * @param ctx - the world context this service registers on (namespace `agyAuth`).
+     * @param home - the world home holding adapter state (`agy-adapter.json`).
+     * @param realHome - the USER's real home (native settings live there).
+     * @param availability - probe of the current machine.
+     */
+    constructor(ctx: Context, home: string, realHome: () => string, availability: () => AgyAuthAvailability);
+    /**
+     * Read the panel state. Pure read: no probe beyond what the caller injected,
+     * no write, safe to call on every expand.
+     * @returns the options, the persisted choice, and the effective form.
+     */
+    get(): Promise<AgyAuthView>;
+    /**
+     * Adopt one form (or clear the choice), persist it to the world home, and
+     * apply the matching mutation to the user's native settings.json right away.
+     *
+     * Applying immediately is the point of the 2026-10-02 ruling: leaving a
+     * previously selected key mode pinned would strand the user's own TUI on
+     * "Gemini API key" with no key exported.
+     * @param request - the requested form.
+     * @returns the panel state after the change.
+     * @throws {TypeError} when `mode` is neither a known form nor null/absent.
+     */
+    set(request?: AgyAuthSetRequest | null): Promise<AgyAuthView>;
+    /** Project the current probe + persisted choice into the panel's view model. */
+    private view;
+}
+/**
+ * The panel's view model. Pure: the probe result, the persisted choice and the
+ * settings path are all injected, which is what makes the ladder and the
+ * annotation rules pinnable under `node --test` with no Cordis context and no
+ * real home.
+ *
+ * @param input - probe, persisted selection (raw; unknown values are ignored), settings path.
+ * @returns the options, the choice, and the form that would actually run.
+ */
+export declare function buildAuthView(input: {
+    availability: AgyAuthAvailability;
+    selected?: unknown;
+    settingsPath: string;
+}): AgyAuthView;
+/**
+ * Validate one `agyAuth/set` request into the mode to adopt.
+ *
+ * `null` means "clear the explicit choice and let the ladder decide" — a real
+ * instruction, not a missing value, which is why an absent field and an
+ * explicit `null` agree while an unknown string is rejected.
+ *
+ * @param request - the wire payload's `request` argument.
+ * @returns the mode to persist, or `null` to clear the choice.
+ * @throws {TypeError} on an unknown mode.
+ */
+export declare function normalizeSetRequest(request?: AgyAuthSetRequest | null): AgyAuthMode | null;

package/agent-agy/dist/agy-auth-gateway.js

@@ -0,0 +1,233 @@
+/**
+ * agy-auth-gateway.ts — the adapter-owned Remote behind the Hub's Antigravity
+ * settings panel (P3, 2026-10-02 user ruling).
+ *
+ * Why a Remote and not a hub route: the auth ladder, the probe results and the
+ * native-settings mutation are ADAPTER config (agent-adapter-dev-rules §12), so
+ * the adapter owns them and the hub only forwards. `TypertRemoteService` +
+ * `@Remote` is the whole mechanism — standard (TC39) method decorators recorded
+ * on the class prototype, read back at dispatch time by the gateway's
+ * source-claim scan. There is NO codegen step and no compiler-injected
+ * metadata, which is why a plain `tsc` adapter build can ship one.
+ *
+ * Wire contract (both halves are pinned by tests):
+ *   request   POST /hub/api?agent=agy
+ *             { type:'client-request', rpcId, method:'agyAuth/get'|'agyAuth/set',
+ *               payload: { args: { request?: AgyAuthSetRequest } } }
+ *   response  { type:'server-response', rpcId, result:{ ok:true, value:<view> } }
+ *
+ * The endpoint namespace is `agyAuth`; the hub's carrier forwards
+ * `envelope.method` verbatim to this world's `typertGateway`.
+ *
+ * Side effects are deliberate and bounded (the 2026-10-02 ruling
+ * 「拥抱用户自己的使用环境」): choosing a form rewrites the USER's real
+ * `~/.gemini/antigravity-cli/settings.json` immediately, so their own TUI
+ * behaves the same way afterwards. The SELECTION itself lives in the world home
+ * (`agy-adapter.json`) — adapter state never leaks into the native home.
+ *
+ * @module agent-agy/agy-auth-gateway
+ */
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
+import { AGY_AUTH_LABELS, AGY_AUTH_ORDER, authSettingsMutation, nativeSettingsPath, resolveAuthMode, } from "./agy-auth.js";
+import { applyAgySettings } from "./agy-cli-client.js";
+import { readAdapterState, writeAdapterState } from "./agy-store.js";
+/**
+ * OAuth is NOT a placeholder any more (measured 2026-10-02): it is the CLI's own
+ * Google sign-in (Agent Platform), the plane headless actually runs on, and the
+ * one that works on this machine with no key, no ADC and no `modelProvider`.
+ * Selecting it means "let the CLI use the account it is already signed in as".
+ */
+function isMode(value) {
+    return typeof value === "string" && AGY_AUTH_ORDER.includes(value);
+}
+/**
+ * The adapter's auth-form Remote. One instance per world context.
+ */
+let AgyAuthGateway = (() => {
+    let _classSuper = TypertRemoteService;
+    let _instanceExtraInitializers = [];
+    let _get_decorators;
+    let _set_decorators;
+    return class AgyAuthGateway extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _get_decorators = [Remote("get")];
+            _set_decorators = [Remote("set")];
+            __esDecorate(this, null, _get_decorators, { kind: "method", name: "get", static: false, private: false, access: { has: obj => "get" in obj, get: obj => obj.get }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _set_decorators, { kind: "method", name: "set", static: false, private: false, access: { has: obj => "set" in obj, get: obj => obj.set }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        home = __runInitializers(this, _instanceExtraInitializers);
+        realHome;
+        availability;
+        /**
+         * @param ctx - the world context this service registers on (namespace `agyAuth`).
+         * @param home - the world home holding adapter state (`agy-adapter.json`).
+         * @param realHome - the USER's real home (native settings live there).
+         * @param availability - probe of the current machine.
+         */
+        constructor(ctx, home, realHome, availability) {
+            super(ctx, "agyAuth");
+            this.home = home;
+            this.realHome = realHome;
+            this.availability = availability;
+        }
+        /**
+         * Read the panel state. Pure read: no probe beyond what the caller injected,
+         * no write, safe to call on every expand.
+         * @returns the options, the persisted choice, and the effective form.
+         */
+        async get() {
+            return this.view();
+        }
+        /**
+         * Adopt one form (or clear the choice), persist it to the world home, and
+         * apply the matching mutation to the user's native settings.json right away.
+         *
+         * Applying immediately is the point of the 2026-10-02 ruling: leaving a
+         * previously selected key mode pinned would strand the user's own TUI on
+         * "Gemini API key" with no key exported.
+         * @param request - the requested form.
+         * @returns the panel state after the change.
+         * @throws {TypeError} when `mode` is neither a known form nor null/absent.
+         */
+        async set(request) {
+            const mode = normalizeSetRequest(request);
+            const state = readAdapterState(this.home);
+            if (mode === null) {
+                const { authMode: _dropped, ...rest } = state;
+                writeAdapterState(this.home, rest);
+            }
+            else {
+                writeAdapterState(this.home, { ...state, authMode: mode });
+            }
+            // The native flip follows the EFFECTIVE form: clearing the choice (or
+            // selecting a form that is not present) must still undo a stale key pin
+            // rather than leave the user's TUI stuck on it.
+            const effective = resolveAuthMode(this.availability(), mode ?? undefined);
+            if (effective !== undefined) {
+                applyAgySettings(this.realHome(), authSettingsMutation(effective));
+            }
+            return this.view();
+        }
+        /** Project the current probe + persisted choice into the panel's view model. */
+        view() {
+            return buildAuthView({
+                availability: this.availability(),
+                selected: readAdapterState(this.home).authMode,
+                settingsPath: nativeSettingsPath(this.realHome()),
+            });
+        }
+    };
+})();
+export { AgyAuthGateway };
+/**
+ * The panel's view model. Pure: the probe result, the persisted choice and the
+ * settings path are all injected, which is what makes the ladder and the
+ * annotation rules pinnable under `node --test` with no Cordis context and no
+ * real home.
+ *
+ * @param input - probe, persisted selection (raw; unknown values are ignored), settings path.
+ * @returns the options, the choice, and the form that would actually run.
+ */
+export function buildAuthView(input) {
+    const { availability, settingsPath } = input;
+    const known = isMode(input.selected) ? input.selected : undefined;
+    const effective = resolveAuthMode(availability, known) ?? null;
+    const methods = AGY_AUTH_ORDER.map((mode) => ({
+        key: mode,
+        label: AGY_AUTH_LABELS[mode],
+        available: availability[mode],
+        placeholder: false,
+        hint: hintFor(mode, availability),
+    }));
+    const note = noteFor(known, effective, availability);
+    return {
+        methods,
+        selected: known ?? null,
+        effective,
+        settingsPath,
+        ...(note === undefined ? {} : { note }),
+    };
+}
+/**
+ * Validate one `agyAuth/set` request into the mode to adopt.
+ *
+ * `null` means "clear the explicit choice and let the ladder decide" — a real
+ * instruction, not a missing value, which is why an absent field and an
+ * explicit `null` agree while an unknown string is rejected.
+ *
+ * @param request - the wire payload's `request` argument.
+ * @returns the mode to persist, or `null` to clear the choice.
+ * @throws {TypeError} on an unknown mode.
+ */
+export function normalizeSetRequest(request) {
+    const requested = request?.mode;
+    if (requested === undefined || requested === null)
+        return null;
+    if (!isMode(requested)) {
+        throw new TypeError(`agyAuth/set: unknown auth mode ${JSON.stringify(requested)}`);
+    }
+    return requested;
+}
+/** One short line per option: what makes it usable, or what is missing. */
+function hintFor(mode, availability) {
+    if (mode === "oauth") {
+        return availability.oauth
+            ? "Uses the CLI's own Google sign-in (Agent Platform) — the default backend."
+            : "No Google sign-in found; run `agy` once to sign in.";
+    }
+    if (mode === "apiKey") {
+        return availability.apiKey
+            ? "A key is available (saved for this runtime or GEMINI_API_KEY)."
+            : "No key yet — save one, or export GEMINI_API_KEY.";
+    }
+    return availability.adc
+        ? "Application Default Credentials found on this machine."
+        : "No ADC found — run `gcloud auth application-default login`.";
+}
+/** Explain the one case the panel cannot show on its own: a stale selection. */
+function noteFor(selected, effective, availability) {
+    if (selected !== undefined && !availability[selected]) {
+        return effective === null
+            ? `${AGY_AUTH_LABELS[selected]} is no longer present on this machine, and no other form is available.`
+            : `${AGY_AUTH_LABELS[selected]} is no longer present on this machine — falling back to ${AGY_AUTH_LABELS[effective]}.`;
+    }
+    if (effective === null)
+        return "No auth form is available yet; sessions will ask for one.";
+    return undefined;
+}

package/agent-agy/dist/agy-auth.d.ts

@@ -0,0 +1,153 @@
+/**
+ * agy-auth.ts — the CLI adapter's auth-form detection, fallback ladder, and
+ * the mutation it applies to the user's LOCAL Antigravity configuration.
+ *
+ * The Antigravity CLI has four auth channels (dev-rules §16a, re-probed
+ * 2026-10-02 against `agy` 1.2.14):
+ *
+ *   1. account sign-in   default, `cloudcode-pa.googleapis.com`; the token
+ *                        lives in the freedesktop Secret Service keyring
+ *                        (`gnome-keyring-daemon`, `org.freedesktop.secrets`,
+ *                        entry `service=gemini username=antigravity`) with a
+ *                        file fallback at `~/.gemini/antigravity-cli/
+ *                        antigravity-oauth-token`;
+ *   2. Gemini API key    `modelProvider: "gemini"` in the CLI's settings.json
+ *                        + `GEMINI_API_KEY` in the launch environment
+ *                        (+ optional `GOOGLE_GEMINI_BASE_URL`);
+ *   3. ADC               `AGY_ADC_AUTH=1` — `adc_auth.go` reports
+ *                        "authenticated via adc (effective: adc)". Credentials
+ *                        are `~/.config/gcloud/application_default_credentials
+ *                        .json` (or a GCE metadata server). NOT the keyring;
+ *   4. BYO gateway       `AGY_LLM_GATEWAY_*` (out of scope; see the spec).
+ *
+ * user ruling 2026-10-02 (supersedes the dev-rules §5 "never write the native
+ * home" default for THIS adapter, under §12 per-adapter discretion):
+ *
+ *   「拥抱用户自己的使用环境」 — this adapter is deliberately the configuration
+ *   surface for the user's LOCAL Antigravity. Selecting a form here really does
+ *   rewrite their `~/.gemini/antigravity-cli/settings.json`, so the TUI they
+ *   already use keeps working afterwards. Paths are hard-coded relative to the
+ *   user's home for exactly that reason.
+ *
+ * Fallback order (same ruling) = Gemini API key → OAuth → ADC. OAuth stays a
+ * PLACEHOLDER this round: no eligible account exists to characterise the
+ * native fields a real sign-in stores, so nothing reports it present.
+ *
+ * Pure: every probe result is injected, so `node --test` pins the ladder; the
+ * one filesystem-touching helper (`nativeSettingsPath`) is a pure path fold.
+ *
+ * @module agent-agy/agy-auth
+ */
+/** The three forms this adapter arbitrates. */
+export type AgyAuthMode = "apiKey" | "oauth" | "adc";
+/** Which forms are present right now (probe result). */
+export interface AgyAuthAvailability {
+    readonly apiKey: boolean;
+    readonly oauth: boolean;
+    readonly adc: boolean;
+}
+/** Declared fallback order (user ruling 2026-10-02). Exported for the UI. */
+export declare const AGY_AUTH_ORDER: readonly AgyAuthMode[];
+/** Human labels, shared by the Hub settings panel and diagnostics. */
+export declare const AGY_AUTH_LABELS: Readonly<Record<AgyAuthMode, string>>;
+/**
+ * The CLI's own app-data directory, hard-coded under the USER's home — the
+ * native Antigravity config we deliberately share with the TUI.
+ *
+ * @param realHome - the user's real `$HOME` (never an isolated override).
+ * @returns the absolute app-data directory.
+ */
+export declare function nativeCliDir(realHome: string): string;
+/**
+ * The CLI's settings file. The binary documents the auth flip here: "To switch
+ * back to signing in, remove `modelProvider` from settings.json and restart
+ * the CLI."
+ *
+ * @param realHome - the user's real `$HOME`.
+ * @returns the absolute settings.json path.
+ */
+export declare function nativeSettingsPath(realHome: string): string;
+/**
+ * The credential file the CLI writes when a Google account signs in. This is
+ * the **Agent Platform** plane: `auth_method: "gcp"`, a `project_id`, and an
+ * access/refresh token pair. It is the backend the interactive TUI uses.
+ *
+ * @param realHome - the user's real `$HOME`.
+ * @returns the absolute path of the CLI's stored sign-in credential.
+ */
+export declare function signinTokenPath(realHome: string): string;
+/**
+ * Is the CLI's own Google sign-in in place?
+ *
+ * Measured 2026-10-02 (this machine): headless CLI reads this plane first, and
+ * when it is present the transport works with NO Gemini API key, NO
+ * `AGY_ADC_AUTH`, and NO `modelProvider` in settings — the run reaches
+ * `result.status: SUCCESS`.
+ *
+ * This is what the auth ladder's middle rung means in practice: not a
+ * placeholder, but "let the CLI use the account it is already signed in as".
+ * It therefore must be DETECTED rather than assumed absent: treating it as
+ * permanently unavailable is what pushed the ladder onto ADC, whose project
+ * has `cloudcode-pa` disabled, and the adapter could never start a turn.
+ *
+ * @param realHome - the user's real `$HOME`.
+ * @returns whether a non-empty sign-in credential is on disk.
+ */
+export declare function hasSigninCredential(realHome: string): boolean;
+/** A settings.json mutation: keys to set, keys to remove. */
+export interface AgySettingsMutation {
+    readonly set: Readonly<Record<string, unknown>>;
+    readonly remove: readonly string[];
+}
+/**
+ * The settings.json change one form needs.
+ *
+ * Key mode pins the Gemini provider. ADC and OAuth need the DEFAULT backend, so
+ * `modelProvider` must be actively REMOVED — merely not setting it would leave
+ * a previously selected key mode in force and the TUI stuck on "Gemini API key"
+ * with no key exported.
+ *
+ * @param mode - the effective form.
+ * @returns the mutation to apply.
+ */
+export declare function authSettingsMutation(mode: AgyAuthMode): AgySettingsMutation;
+/**
+ * Is this mode usable at all right now?
+ *
+ * @param availability - probe result.
+ * @param mode - the form to test.
+ * @returns whether the form is present.
+ */
+export declare function authAvailable(availability: AgyAuthAvailability, mode: AgyAuthMode): boolean;
+/**
+ * Resolve the effective mode: an explicit selection wins when that form is
+ * actually present; otherwise the ladder supplies the first available form.
+ * Nothing present ⇒ `undefined` (the caller gates into onboarding).
+ *
+ * A stale selection (user picked API key, key later removed) deliberately
+ * falls through to the ladder instead of failing — the adapter must not wedge
+ * on config that no longer matches the machine.
+ *
+ * @param availability - probe result.
+ * @param selected - the user's persisted choice, when any.
+ * @returns the effective form, or `undefined` when nothing is available.
+ */
+export declare function resolveAuthMode(availability: AgyAuthAvailability, selected?: AgyAuthMode | undefined): AgyAuthMode | undefined;
+/**
+ * The environment additions the spawned CLI needs for one mode.
+ *
+ * `AGY_CLI_DISABLE_AUTO_UPDATE=1` rides every mode: the CLI silently
+ * self-updated 1.2.12 → 1.2.14 on this machine on 2026-10-02, which makes any
+ * acceptance run unreproducible.
+ *
+ * NOTE there is no HOME handling here at all: the adapter runs the CLI against
+ * the user's REAL home in every mode. Isolating HOME (the previous design) both
+ * hid the very settings.json we now maintain and silently destroyed ADC
+ * (`$HOME/.config/gcloud`) and the keyring — which is how this adapter
+ * previously mis-concluded "the CLI cannot use ADC".
+ *
+ * @param mode - the effective form.
+ * @param apiKey - the resolved key (env or adapter state); empty ⇒ omitted.
+ * @returns env entries to ADD to the child's environment.
+ */
+export declare function authChildEnv(mode: AgyAuthMode, apiKey?: string | undefined): Record<string, string>;