super-dsh 0.1.9 → 0.1.10-e

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

@@ -0,0 +1,173 @@
+/**
+ * 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`
+ */
+import { execFileSync } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/** The Python distribution the bridge imports (`bridge/agy_bridge.py`). */
+export const SDK_PYTHON_PACKAGE = "google-antigravity";
+export function sdkVenvLayout(worldHome) {
+    const dir = join(worldHome, "sdk-venv");
+    return {
+        dir,
+        python: join(dir, "bin", "python"),
+        pip: join(dir, "bin", "pip"),
+        marker: join(worldHome, "sdk-venv.json"),
+        errorLog: join(worldHome, "sdk-venv.error.log"),
+        lock: join(worldHome, "sdk-venv.lock"),
+    };
+}
+/** Read the install marker; undefined when absent or unreadable. */
+export function readSdkVenvRecord(worldHome) {
+    const { marker } = sdkVenvLayout(worldHome);
+    if (!existsSync(marker))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(marker, "utf8"));
+        return typeof parsed === "object" && parsed !== null ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Fast path: the complete venv already exists → the interpreter to use. */
+export function resolveSdkPython(worldHome) {
+    const layout = sdkVenvLayout(worldHome);
+    return existsSync(layout.python) && existsSync(layout.marker) ? layout.python : undefined;
+}
+const DEFAULTS = {
+    basePython: "python3",
+    lockTimeoutMs: 30 * 60 * 1000,
+    lockPollMs: 1000,
+    lockStaleMs: 30 * 60 * 1000,
+};
+function defaultRun(cmd, args) {
+    execFileSync(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+}
+/**
+ * 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 async function ensureSdkVenv(worldHome, opts = {}) {
+    const layout = sdkVenvLayout(worldHome);
+    const now = opts.now ?? Date.now;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const run = opts.run ?? defaultRun;
+    const ready = resolveSdkPython(worldHome);
+    if (ready !== undefined)
+        return ready;
+    mkdirSync(worldHome, { recursive: true });
+    // `acquired === false` means a peer finished the fetch while we waited: the
+    // lock is not ours and MUST NOT be released by this caller.
+    const acquired = await acquireLock(worldHome, layout, now, sleep, opts);
+    if (!acquired)
+        return layout.python;
+    try {
+        // Re-check inside the lock: a concurrent bootstrap may have finished while
+        // we waited, in which case this caller pays nothing.
+        const done = resolveSdkPython(worldHome);
+        if (done !== undefined)
+            return done;
+        const basePython = opts.basePython ?? process.env.AGY_SDK_BASE_PYTHON ?? DEFAULTS.basePython;
+        const stale = existsSync(layout.python);
+        try {
+            opts.trace?.(`sdk-venv: fetching ${SDK_PYTHON_PACKAGE} into ${layout.dir}`);
+            if (!stale)
+                run(basePython, ["-m", "venv", layout.dir]);
+            run(layout.pip, ["install", "-q", SDK_PYTHON_PACKAGE]);
+            if (!existsSync(layout.python)) {
+                throw new Error(`venv created but ${layout.python} is missing`);
+            }
+            const record = {
+                package: SDK_PYTHON_PACKAGE,
+                python: layout.python,
+                installedAt: new Date(now()).toISOString(),
+                createdWith: basePython,
+            };
+            writeFileSync(layout.marker, JSON.stringify(record, null, 2) + "\n");
+            rmSync(layout.errorLog, { force: true });
+            opts.trace?.(`sdk-venv: ready (${layout.python})`);
+            return layout.python;
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            const stamp = new Date(now()).toISOString();
+            try {
+                appendFileSync(layout.errorLog, `[${stamp}] ${SDK_PYTHON_PACKAGE} fetch failed: ${detail}\n`);
+            }
+            catch {
+                /* the trace is best-effort; the throw below is the contract */
+            }
+            throw new Error(`agy-sdk: could not fetch the Python SDK venv (${SDK_PYTHON_PACKAGE}) at ${layout.dir}: ${detail}. ` +
+                `Install it by hand with \`npm run fetch-venv\` (or set AGY_PYTHON to an interpreter that has it). ` +
+                `Trace: ${layout.errorLog}`);
+        }
+    }
+    finally {
+        rmSync(layout.lock, { recursive: true, force: true });
+    }
+}
+/**
+ * mkdir-based mutex with stale-lock reclamation.
+ *
+ * Resolves `true` when THIS caller owns the lock (and must release it), `false`
+ * when a peer completed the fetch while we waited (nothing to release, the
+ * venv is ready). Throws when the wait budget is exhausted.
+ */
+async function acquireLock(worldHome, layout, now, sleep, opts) {
+    const timeout = opts.lockTimeoutMs ?? DEFAULTS.lockTimeoutMs;
+    const poll = opts.lockPollMs ?? DEFAULTS.lockPollMs;
+    const staleMs = opts.lockStaleMs ?? DEFAULTS.lockStaleMs;
+    const deadline = now() + timeout;
+    for (;;) {
+        try {
+            mkdirSync(layout.lock);
+            return true;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        // Someone holds it. Another process may have finished the fetch already.
+        if (resolveSdkPython(worldHome) !== undefined)
+            return false;
+        let ageMs = 0;
+        try {
+            ageMs = now() - statSync(layout.lock).mtimeMs;
+        }
+        catch {
+            continue; // released between the mkdir attempt and the stat — retry now
+        }
+        if (ageMs > staleMs) {
+            opts.trace?.(`sdk-venv: stealing stale lock (age ${Math.round(ageMs / 1000)}s)`);
+            rmSync(layout.lock, { recursive: true, force: true });
+            continue;
+        }
+        if (now() >= deadline) {
+            throw new Error(`agy-sdk: timed out waiting for a concurrent SDK venv fetch (lock ${layout.lock}). ` +
+                `Remove the lock directory if no fetch is running.`);
+        }
+        await sleep(poll);
+    }
+}

package/agent-agy-sdk/dist/world-plugin.d.ts

@@ -0,0 +1,10 @@
+export declare const name = "agent-agy-sdk";
+/** Structural slice of the ctx0 services the mount needs. */
+interface HostContext {
+    provide(name: string, value: unknown): void;
+    inject(deps: string[], callback: (ctx: unknown) => void): unknown;
+    effect?(callback: () => () => void, label?: string): unknown;
+    get(name: string): unknown;
+}
+export declare function apply(ctx: HostContext): void;
+export {};

package/agent-agy-sdk/dist/world-plugin.js

@@ -0,0 +1,82 @@
+/**
+ * agent-agy — the Antigravity (agy) adapter's WORLD plugin (spec S2):
+ * activation IS roster membership.
+ *
+ * AW-B data-plane shape (DL1–DL5 → path-separation T-D), mirroring
+ * `@pgmi-builds/agent-omp/world` and `@pgmi-builds/agent-codex/world` so the
+ * hub sees every foreign runtime through one shape: the world is spawned as a
+ * sibling ROOT context with NO listener and NO webui composition
+ * (`worldMountPatches`) — a pure data plane behind the hub's `/hub` family.
+ *
+ *   1. ctx0 publishes the host mount record (the world's addressability
+ *      entry — no webServer, no fence: those legs retired with the world
+ *      pages) before spawn;
+ *   2. the world's entry row provides the virtual `webServer` (a silent
+ *      sink) plus the neutral `webRuntime` facts its connection row injects;
+ *   3. the hub's `/hub` family answers `?agent=agy` traffic in ctx0's auth
+ *      domain and dispatches into this world's gateway instance (the
+ *      per-label `/<label>/api` + `/<label>/api/remote.mux` mounts retired
+ *      in T-C, `mountWorld` deleted in T-D).
+ */
+import { mkdirSync } from 'node:fs';
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
+import { join } from 'node:path';
+import { spawnWorld, registerAgent, setReady, registerForeignTarget, registerHostMount, worldMountPatches, provisionWorldProfile, resolveInstallAnchor, } from '../../superd-hub/dist/index.js';
+export const name = 'agent-agy-sdk';
+/**
+ * Runtime key — also the mount label. Deliberately NOT `agy`: the hub's roster
+ * (registerAgent) hard-throws on a duplicate key, and this row ships alongside
+ * the CLI row in the same composite. Distinct keys keep both independently
+ * toggleable and make the "both enabled" mistake survivable.
+ */
+const KEY = 'agy-sdk';
+export function apply(ctx) {
+    registerAgent({ key: KEY, label: 'Antigravity (SDK)', ready: false });
+    // Harness resolver (env → ~/.dsh): a consumer install has no DSH_HOME and
+    // no cwd contract — deriving the world root from cwd spawns worlds into a
+    // garbage tree or throws inside apply() and kills the whole host boot.
+    const root = resolveDshHome();
+    // Nested home: the world's DSH data lives INSIDE `agents/<label>` (sessions
+    // / settings / workspaces, and the adapter's dsh-sessions.json mapping).
+    // agy-sdk: the world home carries the DSH-side state AND the lazily fetched
+    // durable Python venv (sdk-venv.ts); nothing is nested for the SDK itself.
+    const worldHome = join(root, 'agents', KEY);
+    mkdirSync(join(worldHome, 'profiles'), { recursive: true });
+    // Publish story: a foreign install has no line bootstrap, so the nested
+    // profile + @pgmi-builds links are provisioned HERE (idempotent).
+    provisionWorldProfile({
+        key: KEY,
+        adapterPkg: '@pgmi-builds/agent-agy-sdk',
+        worldHome,
+    });
+    const world = (async () => {
+        // T-D: no ctx0 listening-stack wait — the mount record is addressability
+        // only and the /hub family wires its own gate in ctx0 (gateway.ts).
+        const dropHostMount = registerHostMount({ key: KEY, labelPath: `/${KEY}` });
+        const ctxW = await spawnWorld({
+            appName: `superd-${KEY}`,
+            profileName: 'web',
+            installAnchor: resolveInstallAnchor(ctx), // lazy: never at module scope — import must stay side-effect-free
+            home: worldHome,
+            dataHome: worldHome,
+            // The host's live table carries this world: spawnWorld republishes a
+            // widened successor before boot imports anything (spec §2.1), and
+            // @pgmi-builds rows resolve from the profile-local links written above.
+            host: ctx,
+            extraPatches: worldMountPatches(KEY),
+        });
+        const gateway = ctxW.get('typertGateway');
+        registerForeignTarget({ key: KEY, gateway });
+        setReady(KEY, true);
+        ctx.effect?.(() => () => {
+            dropHostMount();
+        }, `agent-${KEY}: mount`);
+        return ctxW;
+    })().catch((cause) => {
+        // A failed world degrades to a not-ready roster row; a rejected provided
+        // promise would fail the entire host boot (loader entry apply).
+        console.error(`[super-dsh] ${KEY} world failed:`, cause);
+        return null;
+    });
+    ctx.provide(`superd.world.${KEY}`, world);
+}

package/agent-agy-sdk/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@pgmi-builds/agent-agy-sdk",
+  "version": "0.1.0",
+  "description": "Google Antigravity (Gemini) provider for DeepSeek Harness (dsh) — the OPT-IN SDK transport: drives the google-antigravity Python SDK through a JSONL stdio bridge (bridge/agy_bridge.py, localharness embedded). Auth: adapter-side/GEMINI_API_KEY key, else Vertex over ADC. The agy CLI is never invoked — that is @pgmi-builds/agent-agy. Delivered DISABLED by default (roster key `agy-sdk`): the CLI adapter is the primary path because it reuses the user's existing Antigravity environment. No Python dependency is declared anywhere and there is no postinstall/allow-scripts hook — the durable venv is fetched into the world home on first real use (src/sdk-venv.ts, `npm run fetch-venv`).",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./world": "./dist/world-plugin.js"
+  },
+  "files": [
+    "dist",
+    "bridge",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs",
+    "fetch-venv": "node scripts/fetch-venv.mjs"
+  },
+  "dependencies": {
+    "zod": "3.25.76"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": ">=0.1.5-0 <0.3.0-0",
+    "@deepseek-ai/dsh-llm": ">=0.1.5-0 <0.3.0-0",
+    "@deepseek-ai/dsh-scope": ">=0.1.5-0 <0.3.0-0",
+    "@deepseek-ai/dsh-session": ">=0.1.5-0 <0.3.0-0",
+    "@deepseek-ai/dsh-session-persistence": ">=0.1.5-0 <0.3.0-0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-agent": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-llm": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-scope": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-session": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-session-persistence": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "^5.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js"
+}

package/agent-claude/dist/adapter.js

@@ -4,8 +4,23 @@
  * The browser model selector never touches the Claude agent directly: it is an
  * RPC round-trip through the apiproxy, which reads `ctx.llm.listProviders /
  * listModels / resolveModel` to build the catalog. This adapter answers those
- * queries from the models Claude actually reported (`models.ts`) under the
- * single provider route `claude`.
+ * queries from TWO sources, one route each (the codex twin's one-route-per-
+ * provider shape, 2026-10-04 F-A rework):
+ *
+ *   - the fixed native route `claude` serves the OBSERVED catalog only (raw
+ *     ids — what the CLI itself reports, `models.ts`); its group stays "Claude".
+ *   - one route PER configured provider (route id = provider id) serves that
+ *     provider's curated `models[]` (RAW model ids, `claude-providers.ts`).
+ *
+ * The route/model composition therefore yields selection ids identical to the
+ * old composite keys (`deepseek/deepseek-flash`, `glm/glm-5.3`), so route seeds
+ * and logged selections keep working — the route half simply moved from the
+ * hardcoded `claude` to the provider id itself.
+ *
+ * The curated half follows the codex twin's rule exactly: the store is read
+ * LIVE on every call, so a panel edit is visible to the next catalog query
+ * without re-registration. An absent `worldHome` means observed-only (the
+ * settings-UI round trip and the unit tests).
  *
  * The route id must be `claude`, NOT `claude-code`: the upstream package
  * `@deepseek-ai/dsh-subagent-claude-code` already occupies the subagent
@@ -14,47 +29,107 @@
  * `stream` is never dispatched: Claude owns generation through its own SDK
  * thread, so the adapter only serves catalog/metadata queries. It throws
  * rather than fabricating a wire route the harness would misuse.
+ *
+ * @module agent-claude/adapter
  */
 import { LlmAdapter, LlmError, ReasoningEffortId, } from "@deepseek-ai/dsh-llm";
+import { readProviderStore } from "./claude-providers.js";
 import { readModelCatalog } from "./models.js";
-/** The one provider route every observed Claude model is served under. */
+/** The fixed native route every observed Claude model is served under. */
 export const CLAUDE_PROVIDER_ID = "claude";
-/** Human-readable provider name for selectors and diagnostics. */
+/** Human-readable provider name for the fixed native route. */
 const CLAUDE_PROVIDER_NAME = "Claude";
+/** Whether a provider may be registered as a model route. */
+export function routableProvider(entry) {
+    return entry.models.length > 0;
+}
+/** The route ids a store currently contributes to `ctx.llm`: the fixed `claude`
+ *  route first, then one route per provider that has models (store order). */
+export function routeIds(store) {
+    return [CLAUDE_PROVIDER_ID, ...store.providers.filter(routableProvider).map((entry) => entry.id)];
+}
 export class ClaudeLlmAdapter extends LlmAdapter {
-    providerInfo(_provider) {
-        return { id: CLAUDE_PROVIDER_ID, name: CLAUDE_PROVIDER_NAME };
+    worldHome;
+    /**
+     * @param worldHome - the world's DSH home, holding the curated provider
+     *   store in `<worldHome>/claude-providers.json`. Read on every call (the
+     *   codex twin's rule), so a panel edit is visible to the next catalog query
+     *   without re-registration. Absent = observed-only (the fixed `claude` route).
+     */
+    constructor(worldHome) {
+        super();
+        this.worldHome = worldHome;
+    }
+    /** The curated store entry a provider route id names, or `undefined`. */
+    curatedProvider(providerId) {
+        if (this.worldHome === undefined)
+            return undefined;
+        return readProviderStore(this.worldHome).providers.find((entry) => entry.id === providerId);
+    }
+    providerInfo(provider) {
+        if (provider === CLAUDE_PROVIDER_ID)
+            return { id: CLAUDE_PROVIDER_ID, name: CLAUDE_PROVIDER_NAME };
+        // The display name is the entry's label — for a provider folded in from the
+        // user's own settings that is its endpoint URL, the only name it supplies.
+        return { id: provider, name: this.curatedProvider(provider)?.label ?? provider };
     }
-    async listModels(_provider) {
-        return readModelCatalog().models.map((model) => ({
-            provider: CLAUDE_PROVIDER_ID,
+    async listModels(provider) {
+        if (provider === CLAUDE_PROVIDER_ID) {
+            // Observed catalog only, raw ids exactly as the CLI reported them.
+            return readModelCatalog().models.map((model) => ({
+                provider: CLAUDE_PROVIDER_ID,
+                id: model.id,
+                name: model.label,
+                ...(model.description === undefined ? {} : { description: model.description }),
+            }));
+        }
+        const entry = this.curatedProvider(provider);
+        if (entry === undefined)
+            return [];
+        return entry.models.map((model) => ({
+            provider,
             id: model.id,
-            name: model.label,
-            ...(model.description === undefined ? {} : { description: model.description }),
+            name: model.displayName ?? model.id,
         }));
     }
-    async resolveModel(_provider, model) {
-        const found = readModelCatalog().models.find((candidate) => candidate.id === model);
-        if (found === undefined) {
+    async resolveModel(provider, model) {
+        if (provider === CLAUDE_PROVIDER_ID) {
+            // Observed catalog (primary; unchanged behavior for the native route).
+            const found = readModelCatalog().models.find((candidate) => candidate.id === model);
+            if (found !== undefined) {
+                return {
+                    provider: CLAUDE_PROVIDER_ID,
+                    id: found.id,
+                    name: found.label,
+                    ...(found.description === undefined ? {} : { description: found.description }),
+                    // Only a positive window is real metadata: an absent or zero window must
+                    // never become `context: { contextWindow: 0 }`.
+                    ...(found.contextWindow !== undefined && found.contextWindow > 0
+                        ? { context: { contextWindow: found.contextWindow } }
+                        : {}),
+                    // The CLI's advertised effort levels become adapter-owned reasoning
+                    // efforts (omp thinking.efforts parity); the CLI names no default, so
+                    // none is invented.
+                    ...(found.reasoningEfforts !== undefined && found.reasoningEfforts.length > 0
+                        ? { reasoning: { efforts: found.reasoningEfforts.map((effort) => ({ id: ReasoningEffortId(effort), name: effort })) } }
+                        : {}),
+                };
+            }
             throw new LlmError(`Claude provider "${CLAUDE_PROVIDER_ID}" does not serve model "${model}"`, "MODEL_NOT_FOUND");
         }
-        return {
-            provider: CLAUDE_PROVIDER_ID,
-            id: found.id,
-            name: found.label,
-            ...(found.description === undefined ? {} : { description: found.description }),
-            // Only a positive window is real metadata: an absent or zero window must
-            // never become `context: { contextWindow: 0 }`.
-            ...(found.contextWindow !== undefined && found.contextWindow > 0
-                ? { context: { contextWindow: found.contextWindow } }
-                : {}),
-            // The CLI's advertised effort levels become adapter-owned reasoning
-            // efforts (omp thinking.efforts parity); the CLI names no default, so
-            // none is invented.
-            ...(found.reasoningEfforts !== undefined && found.reasoningEfforts.length > 0
-                ? { reasoning: { efforts: found.reasoningEfforts.map((effort) => ({ id: ReasoningEffortId(effort), name: effort })) } }
-                : {}),
-        };
+        const entry = this.curatedProvider(provider);
+        const curated = entry?.models.find((candidate) => candidate.id === model);
+        if (entry !== undefined && curated !== undefined) {
+            return {
+                provider,
+                id: curated.id,
+                name: curated.displayName ?? curated.id,
+                ...(curated.contextWindow !== undefined && curated.contextWindow > 0
+                    ? { context: { contextWindow: curated.contextWindow } }
+                    : {}),
+            };
+        }
+        throw new LlmError(`Claude provider "${provider}" does not serve model "${model}"`, "MODEL_NOT_FOUND");
     }
     stream(_options) {
         throw new LlmError("the Claude adapter does not stream: Claude owns generation through its SDK thread", "UNSUPPORTED_STREAM");