@grackle-ai/runtime-sdk 0.82.2

package/dist/runtime-installer.js

@@ -0,0 +1,275 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { execFile } from "node:child_process";
+import { createRequire, register } from "node:module";
+import { pathToFileURL } from "node:url";
+import { RUNTIME_MANIFESTS } from "@grackle-ai/common";
+import { logger } from "./logger.js";
+// ─── Constants ──────────────────────────────────────────────
+/** Base directory for isolated per-runtime installs. */
+const RUNTIMES_BASE_DIR = join(homedir(), ".grackle", "runtimes");
+/** Filename for the version/staleness marker in each runtime directory. */
+const MANIFEST_FILENAME = "manifest.json";
+// ─── Dev Mode Detection ─────────────────────────────────────
+/**
+ * Check if PowerLine is running from a monorepo source checkout.
+ * Looks for `rush.json` relative to PowerLine's compiled location
+ * (packages/powerline/dist → 3 levels up).
+ */
+export function isDevMode() {
+    const repoRoot = resolve(import.meta.dirname, "../../../");
+    return existsSync(join(repoRoot, "rush.json"));
+}
+// ─── PowerLine Version ──────────────────────────────────────
+/** Cached PowerLine version string, read once from package.json. */
+let cachedVersion;
+/** Read the PowerLine package version for manifest staleness checks. */
+function getPowerLineVersion() {
+    if (!cachedVersion) {
+        try {
+            const esmRequire = createRequire(import.meta.url);
+            const pkg = esmRequire("../package.json");
+            cachedVersion = pkg.version;
+        }
+        catch {
+            cachedVersion = "unknown";
+        }
+    }
+    return cachedVersion;
+}
+// ─── Single-Flight Guard ────────────────────────────────────
+/** Prevents concurrent installs of the same runtime. */
+const inflight = new Map();
+// ─── vscode-jsonrpc Hook ────────────────────────────────────
+/** Whether the vscode-jsonrpc module resolve hook has been registered. */
+let jsonRpcHookRegistered = false;
+/**
+ * Register a module resolve hook that rewrites `vscode-jsonrpc/node`
+ * to `vscode-jsonrpc/node.js` for Node 22 strict ESM compatibility.
+ * Only needed for the copilot runtime.
+ */
+function registerJsonRpcHook() {
+    if (jsonRpcHookRegistered) {
+        return;
+    }
+    register("data:text/javascript," +
+        encodeURIComponent(`export async function resolve(s,c,n){return s==="vscode-jsonrpc/node"?n("vscode-jsonrpc/node.js",c):n(s,c);}`));
+    jsonRpcHookRegistered = true;
+}
+// ─── Core API ───────────────────────────────────────────────
+/**
+ * Ensure that the npm packages for a runtime are installed in an isolated
+ * directory under `~/.grackle/runtimes/<name>/`.
+ *
+ * **Fast path**: if the persisted manifest matches the current PowerLine
+ * version and package specs, returns immediately (one `readFileSync`).
+ *
+ * **Dev mode**: returns empty string immediately — Rush already resolves
+ * all packages via the monorepo's node_modules.
+ *
+ * @returns The absolute path to the runtime's install directory.
+ */
+export function ensureRuntimeInstalled(runtimeName, options = {}) {
+    // Register module hooks regardless of install path — the hook must be
+    // active before the first SDK import, even when packages are already
+    // installed or resolved via Rush in dev mode.
+    if (runtimeName in RUNTIME_MANIFESTS && RUNTIME_MANIFESTS[runtimeName].needsJsonRpcHook) {
+        registerJsonRpcHook();
+    }
+    // Dev mode: skip the install guard — importFromRuntime() will try a
+    // standard import first, falling back to the isolated runtime directory
+    // (and running doInstall on demand) if the package isn't in the monorepo.
+    if (isDevMode()) {
+        return Promise.resolve("");
+    }
+    if (!(runtimeName in RUNTIME_MANIFESTS)) {
+        return Promise.reject(new Error(`Unknown runtime: ${runtimeName}. No manifest entry found.`));
+    }
+    const manifest = RUNTIME_MANIFESTS[runtimeName];
+    const runtimeDir = join(RUNTIMES_BASE_DIR, runtimeName);
+    // Fast path: check if already installed and up-to-date
+    if (isManifestCurrent(runtimeDir, manifest)) {
+        return Promise.resolve(runtimeDir);
+    }
+    // Single-flight: if another call is already installing this runtime, reuse its promise
+    const existing = inflight.get(runtimeName);
+    if (existing) {
+        return existing;
+    }
+    const installPromise = doInstall(runtimeName, runtimeDir, manifest, options)
+        .then(() => {
+        inflight.delete(runtimeName);
+        return runtimeDir;
+    })
+        .catch((err) => {
+        inflight.delete(runtimeName);
+        throw err;
+    });
+    inflight.set(runtimeName, installPromise);
+    return installPromise;
+}
+/**
+ * Dynamically import a module from an isolated runtime directory.
+ *
+ * In dev mode, falls back to standard `import()` since Rush handles resolution.
+ *
+ * @param runtimeName - Runtime identifier (e.g. "claude-code")
+ * @param packageName - npm package name to import (e.g. `\@anthropic-ai/claude-agent-sdk`)
+ * @returns The imported module
+ */
+export async function importFromRuntime(runtimeName, packageName) {
+    if (isDevMode()) {
+        try {
+            return await import(packageName);
+        }
+        catch (err) {
+            // Only fall back to runtime directory for module-not-found errors.
+            // Rethrow real runtime errors (init failures, syntax errors, etc.)
+            const code = err.code;
+            if (code !== "ERR_MODULE_NOT_FOUND" && code !== "MODULE_NOT_FOUND") {
+                throw err;
+            }
+            // Package not in monorepo devDependencies — install on demand and
+            // resolve from the isolated runtime directory below.
+            if (!(runtimeName in RUNTIME_MANIFESTS)) {
+                throw err;
+            }
+            const manifest = RUNTIME_MANIFESTS[runtimeName];
+            const runtimeDir = join(RUNTIMES_BASE_DIR, runtimeName);
+            if (!isManifestCurrent(runtimeDir, manifest)) {
+                logger.info({ runtimeName, packageName }, "Package not found in monorepo — installing via lazy runtime installer");
+                await doInstall(runtimeName, runtimeDir, manifest, {});
+            }
+        }
+    }
+    const runtimeDir = join(RUNTIMES_BASE_DIR, runtimeName);
+    try {
+        const esmRequire = createRequire(join(runtimeDir, "package.json"));
+        let resolved;
+        try {
+            resolved = esmRequire.resolve(packageName);
+        }
+        catch {
+            // CJS resolve fails for ESM-only packages (exports map without "require" condition).
+            // Fall back to reading the package's main/exports field directly.
+            const pkgJsonPath = join(runtimeDir, "node_modules", ...packageName.split("/"), "package.json");
+            const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+            const exportsRoot = pkg.exports?.["."];
+            let entryPoint;
+            if (typeof exportsRoot === "string") {
+                entryPoint = exportsRoot;
+            }
+            else if (typeof exportsRoot === "object") {
+                entryPoint = exportsRoot.import || exportsRoot.default || pkg.main || "index.js";
+            }
+            else {
+                entryPoint = pkg.main || "index.js";
+            }
+            resolved = join(runtimeDir, "node_modules", ...packageName.split("/"), entryPoint);
+        }
+        return import(pathToFileURL(resolved).href);
+    }
+    catch (resolveErr) {
+        throw new Error(`Failed to resolve "${packageName}" from runtime directory ${runtimeDir}. `
+            + `The lazy installer may have failed — check the logs above for details. `
+            + `Manual fix: cd ${runtimeDir} && npm install`, { cause: resolveErr });
+    }
+}
+/**
+ * Get the path to the `.bin` directory inside a runtime's node_modules.
+ * Used to add runtime-specific CLI binaries to PATH when spawning agent subprocesses.
+ *
+ * @param runtimeName - Runtime identifier (e.g. "codex-acp")
+ * @returns Absolute path to `~/.grackle/runtimes/<name>/node_modules/.bin`
+ */
+export function getRuntimeBinDirectory(runtimeName) {
+    if (isDevMode()) {
+        // In dev mode, prefer the isolated runtime directory if it exists (packages
+        // removed from devDependencies); fall back to the monorepo's bin.
+        const monoBin = resolve(import.meta.dirname, "../node_modules/.bin");
+        const runtimeBin = join(RUNTIMES_BASE_DIR, runtimeName, "node_modules", ".bin");
+        return existsSync(runtimeBin) ? runtimeBin : monoBin;
+    }
+    return join(RUNTIMES_BASE_DIR, runtimeName, "node_modules", ".bin");
+}
+// ─── Internal Helpers ───────────────────────────────────────
+/** Check if the persisted manifest matches the current state. */
+function isManifestCurrent(runtimeDir, manifest) {
+    const manifestPath = join(runtimeDir, MANIFEST_FILENAME);
+    try {
+        const raw = readFileSync(manifestPath, "utf8");
+        const persisted = JSON.parse(raw);
+        if (persisted.powerlineVersion !== getPowerLineVersion()) {
+            return false;
+        }
+        // Compare package specs
+        const currentKeys = Object.keys(manifest.packages).sort();
+        const persistedKeys = Object.keys(persisted.packages).sort();
+        if (currentKeys.length !== persistedKeys.length) {
+            return false;
+        }
+        for (let i = 0; i < currentKeys.length; i++) {
+            if (currentKeys[i] !== persistedKeys[i]) {
+                return false;
+            }
+            if (manifest.packages[currentKeys[i]] !== persisted.packages[currentKeys[i]]) {
+                return false;
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Perform the actual npm install and write the manifest. */
+async function doInstall(runtimeName, runtimeDir, manifest, options) {
+    const { eventCallback } = options;
+    const packageNames = Object.entries(manifest.packages)
+        .map(([name, version]) => `${name}@${version}`)
+        .join(", ");
+    logger.info({ runtimeName, packages: packageNames }, "Installing runtime packages");
+    if (eventCallback) {
+        eventCallback(`Installing ${runtimeName} runtime (${packageNames})...`);
+    }
+    // Ensure directory exists
+    mkdirSync(runtimeDir, { recursive: true });
+    // Write package.json
+    const packageJson = {
+        name: `grackle-runtime-${runtimeName}`,
+        version: "1.0.0",
+        private: true,
+        dependencies: { ...manifest.packages },
+    };
+    writeFileSync(join(runtimeDir, "package.json"), JSON.stringify(packageJson, null, 2));
+    // Run npm install asynchronously to avoid blocking the event loop.
+    // shell:true is needed on Windows where npm is a .cmd batch file.
+    await new Promise((resolve, reject) => {
+        execFile("npm", ["install", "--omit=dev", "--registry=https://registry.npmjs.org"], { cwd: runtimeDir, timeout: 120_000, shell: true, maxBuffer: 10 * 1024 * 1024 }, (err, _stdout, stderr) => {
+            if (err) {
+                const detail = err.message || String(err);
+                const stderrSnippet = stderr ? stderr.slice(0, 500) : "";
+                logger.error({ runtimeName, runtimeDir, err, stderrSnippet }, "npm install failed for runtime packages");
+                reject(new Error(`Failed to install ${runtimeName} runtime packages. Run manually:\n`
+                    + `  cd ${runtimeDir} && npm install\n`
+                    + `Cause: ${detail}`
+                    + (stderrSnippet ? `\nStderr: ${stderrSnippet}` : "")));
+            }
+            else {
+                resolve();
+            }
+        });
+    });
+    // Write manifest for staleness checking
+    const persistedManifest = {
+        powerlineVersion: getPowerLineVersion(),
+        packages: { ...manifest.packages },
+    };
+    writeFileSync(join(runtimeDir, MANIFEST_FILENAME), JSON.stringify(persistedManifest, null, 2));
+    logger.info({ runtimeName, runtimeDir }, "Runtime packages installed successfully");
+    if (eventCallback) {
+        eventCallback(`${runtimeName} runtime installed successfully`);
+    }
+}
+//# sourceMappingURL=runtime-installer.js.map

package/dist/runtime-installer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-installer.js","sourceRoot":"","sources":["../src/runtime-installer.ts"],"names":[],"mappings":"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"}

package/dist/runtime-utils.d.ts

@@ -0,0 +1,97 @@
+import type { AgentEvent } from "./runtime.js";
+import type { AsyncQueue } from "./async-queue.js";
+/**
+ * Higher-level git repository abstraction for workspace resolution.
+ *
+ * Unlike the raw `GitExecutor` in worktree.ts (which wraps a single `exec(args)` call),
+ * this interface provides domain-specific methods for repository discovery and branch checkout.
+ */
+export interface GitRepository {
+    /** Check if a directory is inside a git repository. */
+    isRepo(dir: string): Promise<boolean>;
+    /** Return the git toplevel for a directory, or undefined if not a repo. */
+    toplevel(dir: string): Promise<string | undefined>;
+    /** Check out (or create) a branch in the main working tree. */
+    checkoutBranch(repoPath: string, branch: string): Promise<void>;
+}
+/** Default implementation that shells out to the real git binary. */
+export declare const NODE_GIT_REPOSITORY: GitRepository;
+/** Filesystem operations for workspace discovery. */
+export interface WorkspaceLocator {
+    /** Check if a path exists. */
+    exists(path: string): boolean;
+    /** List entries in a directory. Returns empty array on failure. */
+    readDirectory(path: string): string[];
+}
+/** Default implementation using real Node.js fs. */
+export declare const NODE_WORKSPACE_LOCATOR: WorkspaceLocator;
+/** Options for resolving the working directory. */
+export interface ResolveWorkingDirectoryOptions {
+    /** Git branch to check out in a worktree. */
+    branch?: string;
+    /** Base path for worktree creation or working directory override. */
+    workingDirectory?: string;
+    /** When true, create git worktrees for branch isolation. When false, checkout in place. Defaults to true when undefined. */
+    useWorktrees?: boolean;
+    /** Event queue to push system messages to. */
+    eventQueue: AsyncQueue<AgentEvent>;
+    /**
+     * When true, the `/workspace` fallback requires the directory to be non-empty.
+     * Only claude-code sets this — codex and copilot accept empty workspaces.
+     */
+    requireNonEmpty?: boolean;
+    /** @internal Git repository abstraction for testing. */
+    git?: GitRepository;
+    /** @internal Workspace locator abstraction for testing. */
+    locator?: WorkspaceLocator;
+}
+/**
+ * Find the git repository root from a set of well-known workspace paths.
+ *
+ * Checks (in order):
+ * 1. The provided basePath (if given)
+ * 2. /workspace (Docker convention)
+ * 3. /workspaces/* (GitHub Codespaces convention — picks the first git repo found)
+ *
+ * Returns the first path that exists and is a git repository, or undefined.
+ */
+export declare function findGitRepoPath(basePath?: string, git?: GitRepository, locator?: WorkspaceLocator): Promise<string | undefined>;
+/**
+ * Resolve the working directory for an agent session.
+ *
+ * Tries worktree creation first (when branch + basePath are provided and
+ * useWorktrees is not false), auto-detecting the git repo if the provided
+ * basePath is not a git repo. Falls back to workspace directories on failure.
+ *
+ * When useWorktrees is explicitly false, checks out the branch directly in the
+ * main working tree instead of creating a worktree. When useWorktrees is
+ * undefined (proto3 unset), it defaults to true.
+ */
+export declare function resolveWorkingDirectory(options: ResolveWorkingDirectoryOptions): Promise<string | undefined>;
+/**
+ * Convert Grackle MCP server configs (keyed object) to ACP format (named array).
+ *
+ * Grackle format: `{ "name": { command, args, env, ... } }`
+ * ACP format:     `[{ name, type: "stdio"|"http", command, args, env, ... }]`
+ */
+export declare function convertMcpServers(servers: Record<string, unknown> | undefined): Record<string, unknown>[];
+/** Resolved MCP configuration returned by resolveMcpServers. */
+export interface ResolvedMcpConfig {
+    servers: Record<string, unknown> | undefined;
+    disallowedTools: string[];
+}
+/** Broker configuration for injecting the HTTP MCP server entry. Matches SpawnOptions.mcpBroker. */
+export interface BrokerConfig {
+    /** Full URL of the broker's /mcp endpoint. */
+    url: string;
+    /** Scoped Bearer token for this session. */
+    token: string;
+}
+/**
+ * Load MCP server configurations from the shared GRACKLE_MCP_CONFIG file and spawn options.
+ *
+ * Also reads `disallowedTools` and filters matching tools from MCP server configs.
+ * When `brokerConfig` is provided, injects an HTTP-based Grackle MCP server entry.
+ */
+export declare function resolveMcpServers(spawnMcpServers?: Record<string, unknown>, brokerConfig?: BrokerConfig): ResolvedMcpConfig;
+//# sourceMappingURL=runtime-utils.d.ts.map

package/dist/runtime-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-utils.d.ts","sourceRoot":"","sources":["../src/runtime-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AASnD;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACnD,+DAA+D;IAC/D,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAED,qEAAqE;AACrE,eAAO,MAAM,mBAAmB,EAAE,aA6B9B,CAAC;AAEL,qDAAqD;AACrD,MAAM,WAAW,gBAAgB;IAC/B,8BAA8B;IAC9B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,mEAAmE;IACnE,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACvC;AAED,oDAAoD;AACpD,eAAO,MAAM,sBAAsB,EAAE,gBASpC,CAAC;AAIF,mDAAmD;AACnD,MAAM,WAAW,8BAA8B;IAC7C,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4HAA4H;IAC5H,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,8CAA8C;IAC9C,UAAU,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;IACnC;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,wDAAwD;IACxD,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,QAAQ,CAAC,EAAE,MAAM,EACjB,GAAG,GAAE,aAAmC,EACxC,OAAO,GAAE,gBAAyC,GACjD,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAuB7B;AAiCD;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,8BAA8B,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAkElH;AAID;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAyCzG;AAID,gEAAgE;AAChE,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC7C,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,oGAAoG;AACpG,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;CACf;AAGD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzC,YAAY,CAAC,EAAE,YAAY,GAC1B,iBAAiB,CAkEnB"}