@grackle-ai/runtime-sdk 0.82.2

package/dist/runtime-utils.js

@@ -0,0 +1,291 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { ensureWorktree } from "./worktree.js";
+import { logger } from "./logger.js";
+/** Default implementation that shells out to the real git binary. */
+export const NODE_GIT_REPOSITORY = (() => {
+    const execFileAsync = promisify(execFile);
+    return {
+        async isRepo(dir) {
+            try {
+                await execFileAsync("git", ["rev-parse", "--git-dir"], { cwd: dir });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        async toplevel(dir) {
+            try {
+                const { stdout } = await execFileAsync("git", ["rev-parse", "--show-toplevel"], { cwd: dir });
+                return stdout.trim();
+            }
+            catch {
+                return undefined;
+            }
+        },
+        async checkoutBranch(repoPath, branch) {
+            try {
+                // "--" prevents branch names starting with "-" from being interpreted as flags
+                await execFileAsync("git", ["checkout", "--", branch], { cwd: repoPath });
+            }
+            catch {
+                // Branch doesn't exist yet — create it
+                await execFileAsync("git", ["checkout", "-b", branch], { cwd: repoPath });
+            }
+        },
+    };
+})();
+/** Default implementation using real Node.js fs. */
+export const NODE_WORKSPACE_LOCATOR = {
+    exists: existsSync,
+    readDirectory(path) {
+        try {
+            return readdirSync(path);
+        }
+        catch {
+            return [];
+        }
+    },
+};
+/**
+ * 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 async function findGitRepoPath(basePath, git = NODE_GIT_REPOSITORY, locator = NODE_WORKSPACE_LOCATOR) {
+    // Try the explicitly provided path first, resolving to the actual repo root
+    if (basePath && locator.exists(basePath) && await git.isRepo(basePath)) {
+        return (await git.toplevel(basePath)) ?? basePath;
+    }
+    // Docker convention
+    if (locator.exists("/workspace") && await git.isRepo("/workspace")) {
+        return (await git.toplevel("/workspace")) ?? "/workspace";
+    }
+    // GitHub Codespaces convention: /workspaces/<repo-name>
+    if (locator.exists("/workspaces")) {
+        const entries = locator.readDirectory("/workspaces");
+        for (const entry of entries) {
+            const candidate = `/workspaces/${entry}`;
+            if (locator.exists(candidate) && await git.isRepo(candidate)) {
+                return (await git.toplevel(candidate)) ?? candidate;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Find any existing workspace directory (git repo or not) for fallback use.
+ * Used when worktree setup fails and we just need a working directory.
+ */
+function findWorkspaceDir(basePath, requireNonEmpty, locator = NODE_WORKSPACE_LOCATOR) {
+    const candidates = [basePath, "/workspace"];
+    // Also check /workspaces/* for Codespaces
+    if (locator.exists("/workspaces")) {
+        for (const entry of locator.readDirectory("/workspaces")) {
+            candidates.push(`/workspaces/${entry}`);
+        }
+    }
+    for (const dir of candidates) {
+        if (dir && locator.exists(dir)) {
+            if (requireNonEmpty) {
+                if (locator.readDirectory(dir).length === 0) {
+                    continue;
+                }
+            }
+            return dir;
+        }
+    }
+    return 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 async function resolveWorkingDirectory(options) {
+    const { branch, workingDirectory, useWorktrees = true, eventQueue, requireNonEmpty, git = NODE_GIT_REPOSITORY, locator = NODE_WORKSPACE_LOCATOR, } = options;
+    const ts = () => new Date().toISOString();
+    if (branch && workingDirectory && useWorktrees) {
+        // Worktrees enabled — create a worktree for the branch.
+        // Auto-detect the actual git repo path — the server may send a default
+        // like "/workspace" that doesn't match the actual layout (e.g. Codespaces
+        // use /workspaces/<repo>).
+        const repoPath = await findGitRepoPath(workingDirectory, git, locator);
+        if (repoPath) {
+            try {
+                const wt = await ensureWorktree(repoPath, branch);
+                eventQueue.push({ type: "system", timestamp: ts(), content: `Worktree ready: ${wt.worktreePath} (branch: ${branch}, created: ${String(wt.created)}, synced: ${String(wt.synced)})` });
+                return wt.worktreePath;
+            }
+            catch (wtErr) {
+                eventQueue.push({ type: "system", timestamp: ts(), content: `Worktree setup failed (${wtErr instanceof Error ? wtErr.message : String(wtErr)}), falling back to workspace` });
+            }
+        }
+        else {
+            eventQueue.push({ type: "system", timestamp: ts(), content: `No git repo found at ${workingDirectory} or well-known paths, falling back to workspace` });
+        }
+        // Worktree failed — fall back to best available workspace
+        const fallback = findWorkspaceDir(workingDirectory, requireNonEmpty, locator);
+        if (fallback) {
+            return fallback;
+        }
+        return undefined;
+    }
+    if (branch && !useWorktrees) {
+        // Worktrees disabled — check out the branch in the main working tree.
+        // Use workingDirectory as the repo hint if provided.
+        const repoPath = await findGitRepoPath(workingDirectory, git, locator);
+        if (repoPath) {
+            try {
+                await git.checkoutBranch(repoPath, branch);
+                eventQueue.push({ type: "system", timestamp: ts(), content: `Checked out branch '${branch}' in main working tree: ${repoPath}` });
+                return repoPath;
+            }
+            catch (checkoutErr) {
+                eventQueue.push({ type: "system", timestamp: ts(), content: `Branch checkout failed (${checkoutErr instanceof Error ? checkoutErr.message : String(checkoutErr)}), falling back to workspace` });
+            }
+        }
+        else {
+            eventQueue.push({ type: "system", timestamp: ts(), content: `No git repo found${workingDirectory ? ` at ${workingDirectory}` : ""} for branch checkout, falling back to workspace` });
+        }
+        // Checkout failed — fall back to best available workspace
+        const fallback = findWorkspaceDir(workingDirectory, requireNonEmpty, locator);
+        if (fallback) {
+            return fallback;
+        }
+        return undefined;
+    }
+    // No branch requested — just find a workspace directory
+    return findWorkspaceDir(workingDirectory, requireNonEmpty, locator);
+}
+// ─── ACP MCP server conversion ─────────────────────────────
+/**
+ * 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 function convertMcpServers(servers) {
+    if (!servers) {
+        return [];
+    }
+    return Object.entries(servers)
+        .filter(([, config]) => typeof config === "object" && config !== null && !Array.isArray(config))
+        .map(([name, config]) => {
+        const cfg = config;
+        // Detect transport: HTTP servers have type:"http" or a url field; everything else is stdio
+        const isHttp = cfg.type === "http" || cfg.url;
+        const result = {
+            name,
+            type: isHttp ? "http" : "stdio",
+        };
+        if (isHttp) {
+            // HTTP transport: url is required, headers must be array of {name, value}
+            result.url = cfg.url;
+            if (cfg.headers && typeof cfg.headers === "object" && !Array.isArray(cfg.headers)) {
+                result.headers = Object.entries(cfg.headers)
+                    .map(([k, v]) => ({ name: k, value: v }));
+            }
+            else if (Array.isArray(cfg.headers)) {
+                result.headers = cfg.headers;
+            }
+        }
+        else {
+            // Stdio transport: command, args, env required
+            result.command = (cfg.command || "");
+            result.args = Array.isArray(cfg.args) ? cfg.args : [];
+            // env must be array of {name, value} — convert from object if needed
+            if (cfg.env && typeof cfg.env === "object" && !Array.isArray(cfg.env)) {
+                result.env = Object.entries(cfg.env)
+                    .map(([k, v]) => ({ name: k, value: v }));
+            }
+            else if (Array.isArray(cfg.env)) {
+                result.env = cfg.env;
+            }
+            else {
+                result.env = [];
+            }
+        }
+        return result;
+    });
+}
+/**
+ * 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 function resolveMcpServers(spawnMcpServers, brokerConfig) {
+    let servers = {};
+    let disallowedTools = [];
+    const mcpConfigPath = process.env.GRACKLE_MCP_CONFIG;
+    if (mcpConfigPath && existsSync(mcpConfigPath)) {
+        try {
+            const mcpConfig = JSON.parse(readFileSync(mcpConfigPath, "utf8"));
+            if (mcpConfig.mcpServers && typeof mcpConfig.mcpServers === "object") {
+                servers = { ...servers, ...mcpConfig.mcpServers };
+            }
+            if (Array.isArray(mcpConfig.disallowedTools)) {
+                disallowedTools = mcpConfig.disallowedTools.filter((t) => typeof t === "string");
+            }
+        }
+        catch { /* ignore malformed config */ }
+    }
+    if (spawnMcpServers) {
+        servers = { ...servers, ...spawnMcpServers };
+    }
+    // Inject the Grackle MCP server entry when broker config is provided
+    if (!servers.grackle && brokerConfig) {
+        servers.grackle = {
+            type: "http",
+            url: brokerConfig.url,
+            headers: { Authorization: `Bearer ${brokerConfig.token}` },
+            // tools: ["*"] is required by Copilot SDK (MCPServerConfigBase.tools is mandatory).
+            // Claude Agent SDK ignores unknown fields, Codex CLI flattens to --config.
+            tools: ["*"],
+        };
+    }
+    // Filter disallowed tools from MCP server configs. The disallowedTools list
+    // uses the format "mcp__<serverName>__<toolName>", matching Claude Code's convention.
+    if (disallowedTools.length > 0) {
+        for (const [serverName, serverConfig] of Object.entries(servers)) {
+            if (typeof serverConfig !== "object" || serverConfig === null) {
+                continue;
+            }
+            const cfg = serverConfig;
+            if (!Array.isArray(cfg.tools)) {
+                continue;
+            }
+            const prefix = `mcp__${serverName}__`;
+            const blocked = new Set(disallowedTools.filter((t) => t.startsWith(prefix)).map((t) => t.slice(prefix.length)));
+            if (blocked.size > 0) {
+                cfg.tools = cfg.tools.filter((t) => !blocked.has(t));
+                if (cfg.tools.length === 0) {
+                    delete servers[serverName];
+                    logger.info({ serverName, blocked: [...blocked] }, "Removed MCP server (all tools disallowed)");
+                }
+                else {
+                    logger.info({ serverName, blocked: [...blocked] }, "Filtered disallowed tools from MCP server");
+                }
+            }
+        }
+    }
+    return {
+        servers: Object.keys(servers).length > 0 ? servers : undefined,
+        disallowedTools,
+    };
+}
+//# sourceMappingURL=runtime-utils.js.map

package/dist/runtime-utils.js.map

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

package/dist/runtime.d.ts

@@ -0,0 +1,63 @@
+import type { AgentEventType, SessionStatus, PipeMode } from "@grackle-ai/common";
+/** A single event emitted by an agent during execution. */
+export interface AgentEvent {
+    type: AgentEventType;
+    timestamp: string;
+    content: string;
+    raw?: unknown;
+}
+/** Parameters for spawning a new agent session. */
+export interface SpawnOptions {
+    sessionId: string;
+    prompt: string;
+    model: string;
+    maxTurns: number;
+    branch?: string;
+    workingDirectory?: string;
+    useWorktrees?: boolean;
+    systemContext?: string;
+    workspaceId?: string;
+    taskId?: string;
+    /** MCP server configurations to pass to the agent SDK. */
+    mcpServers?: Record<string, unknown>;
+    /** SDK hook callbacks (e.g. Stop hooks). Only supported by the Claude Code runtime; other runtimes ignore this field. */
+    hooks?: Record<string, unknown>;
+    /** MCP broker connection details. Both url and token must be present together. */
+    mcpBroker?: {
+        url: string;
+        token: string;
+    };
+    /** Script source code for script personas (e.g. GenAIScript). */
+    scriptContent?: string;
+    /** Pipe mode for parent↔child IPC ("sync", "async", "detach", or undefined for no pipe). */
+    pipe?: PipeMode;
+}
+/** Parameters for resuming an existing agent session. */
+export interface ResumeOptions {
+    sessionId: string;
+    runtimeSessionId: string;
+}
+/** Handle for an in-progress agent session with streaming, input, and kill capabilities. */
+export interface AgentSession {
+    id: string;
+    runtimeName: string;
+    runtimeSessionId: string;
+    status: SessionStatus;
+    /** Yield events as the agent runs. */
+    stream(): AsyncIterable<AgentEvent>;
+    /** Send user input to a session that is waiting for it. */
+    sendInput(text: string): void;
+    /** Forcefully terminate the session with an optional reason. */
+    kill(reason?: string): void;
+    /** Drain any buffered events that were not yet consumed by the stream. */
+    drainBufferedEvents(): AgentEvent[];
+}
+/** Contract for pluggable agent runtime implementations (e.g. Claude Code, stub). */
+export interface AgentRuntime {
+    name: string;
+    /** Create and start a new agent session. */
+    spawn(opts: SpawnOptions): AgentSession;
+    /** Resume a previously suspended session. */
+    resume(opts: ResumeOptions): AgentSession;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAElF,2DAA2D;AAC3D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,mDAAmD;AACnD,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,yHAAyH;IACzH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,kFAAkF;IAClF,SAAS,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4FAA4F;IAC5F,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,4FAA4F;AAC5F,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,aAAa,CAAC;IACtB,sCAAsC;IACtC,MAAM,IAAI,aAAa,CAAC,UAAU,CAAC,CAAC;IACpC,2DAA2D;IAC3D,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,gEAAgE;IAChE,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,0EAA0E;IAC1E,mBAAmB,IAAI,UAAU,EAAE,CAAC;CACrC;AAED,qFAAqF;AACrF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,CAAC;IACxC,6CAA6C;IAC7C,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,YAAY,CAAC;CAC3C"}

package/dist/runtime.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":""}

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.57.7"
+    }
+  ]
+}

package/dist/worktree.d.ts

@@ -0,0 +1,30 @@
+/** Abstraction over git command execution used by worktree operations. */
+export interface GitExecutor {
+    /** Run a git command and return stdout/stderr. */
+    exec(args: string[], options: {
+        cwd: string;
+        timeout?: number;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+}
+/** Filesystem operations used by worktree functions. */
+export interface WorktreeFileSystem {
+    /** Check whether a path exists. */
+    existsSync(path: string): boolean;
+}
+export interface WorktreeResult {
+    worktreePath: string;
+    branch: string;
+    created: boolean;
+    /** True if `git fetch origin` succeeded before worktree creation. */
+    synced: boolean;
+}
+/** @internal Sanitize a branch name for use in file paths. Exported for testing. */
+export declare function sanitizeBranch(branch: string): string;
+/** @internal Compute the worktree directory path for a given branch. Exported for testing. */
+export declare function worktreeDir(basePath: string, branch: string): string;
+export declare function ensureWorktree(basePath: string, branch: string, git?: GitExecutor, fileSystem?: WorktreeFileSystem): Promise<WorktreeResult>;
+export declare function removeWorktree(basePath: string, branch: string, git?: GitExecutor): Promise<void>;
+//# sourceMappingURL=worktree.d.ts.map

package/dist/worktree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../src/worktree.ts"],"names":[],"mappings":"AAWA,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/G;AAWD,wDAAwD;AACxD,MAAM,WAAW,kBAAkB;IACjC,mCAAmC;IACnC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAOD,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,8FAA8F;AAC9F,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAUpE;AAmCD,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,GAAG,GAAE,WAA+B,EACpC,UAAU,GAAE,kBAA8C,GACzD,OAAO,CAAC,cAAc,CAAC,CAwCzB;AAED,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,GAAG,GAAE,WAA+B,GACnC,OAAO,CAAC,IAAI,CAAC,CAOf"}

package/dist/worktree.js

@@ -0,0 +1,115 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync as existsSyncNode } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { logger } from "./logger.js";
+const execRaw = promisify(execFile);
+/** Timeout for `git fetch origin` in milliseconds. */
+const FETCH_TIMEOUT_MS = 30_000;
+/** Default implementation that shells out to the real git binary. */
+const NODE_GIT_EXECUTOR = {
+    async exec(args, options) {
+        const shell = process.env.SHELL || true;
+        const result = await execRaw("git", args, { ...options, shell });
+        return { stdout: String(result.stdout), stderr: String(result.stderr) };
+    },
+};
+/** Default implementation using real Node.js fs. */
+const NODE_WORKTREE_FILE_SYSTEM = {
+    existsSync: existsSyncNode,
+};
+/** @internal Sanitize a branch name for use in file paths. Exported for testing. */
+export function sanitizeBranch(branch) {
+    return branch.replace(/[^a-zA-Z0-9/_-]/g, "-");
+}
+/** @internal Compute the worktree directory path for a given branch. Exported for testing. */
+export function worktreeDir(basePath, branch) {
+    const sanitized = sanitizeBranch(branch).replace(/\//g, "-");
+    const parent = dirname(basePath);
+    // When repo is at a root-level path (e.g. /workspace in Docker),
+    // dirname returns "/" which is typically not writable. Fall back to $HOME.
+    if (parent === "/" || parent === "\\") {
+        const home = process.env.HOME || process.env.USERPROFILE || basePath;
+        return resolve(home, ".grackle-worktrees", sanitized);
+    }
+    return resolve(parent, ".grackle-worktrees", sanitized);
+}
+/**
+ * Fetch from origin and detect the default branch name.
+ *
+ * Returns `synced: true` with a `startPoint` like `origin/main` on success,
+ * or `synced: false` with no start point on failure (so the caller can still
+ * create the worktree from local HEAD).
+ */
+async function fetchAndDetectDefault(basePath, git) {
+    try {
+        await git.exec(["fetch", "origin"], { cwd: basePath, timeout: FETCH_TIMEOUT_MS });
+    }
+    catch (err) {
+        logger.warn({ err }, "git fetch origin failed — worktree will branch from local HEAD");
+        return { synced: false, startPoint: undefined };
+    }
+    // Detect the remote's default branch (e.g. refs/remotes/origin/main)
+    let defaultBranch = "origin/main";
+    try {
+        const { stdout } = await git.exec(["symbolic-ref", "refs/remotes/origin/HEAD"], { cwd: basePath });
+        const trimmed = stdout.trim(); // e.g. "refs/remotes/origin/main"
+        if (trimmed.startsWith("refs/remotes/")) {
+            defaultBranch = trimmed.slice("refs/remotes/".length); // "origin/main"
+        }
+    }
+    catch {
+        logger.warn("Could not detect default branch via symbolic-ref, falling back to origin/main");
+    }
+    return { synced: true, startPoint: defaultBranch };
+}
+export async function ensureWorktree(basePath, branch, git = NODE_GIT_EXECUTOR, fileSystem = NODE_WORKTREE_FILE_SYSTEM) {
+    // Pre-check: verify basePath is a git repository
+    try {
+        await git.exec(["rev-parse", "--git-dir"], { cwd: basePath });
+    }
+    catch {
+        throw new Error(`Not a git repository: ${basePath}`);
+    }
+    // Pre-check: verify the git repo is writable (worktrees modify .git internals)
+    try {
+        await git.exec(["status", "--porcelain"], { cwd: basePath });
+    }
+    catch (err) {
+        throw new Error(`Git repo not writable: ${basePath} (${err instanceof Error ? err.message : String(err)})`);
+    }
+    const wtPath = worktreeDir(basePath, branch);
+    if (fileSystem.existsSync(wtPath)) {
+        return { worktreePath: wtPath, branch, created: false, synced: false };
+    }
+    // Fetch origin so the new worktree branches from an up-to-date commit
+    const { synced, startPoint } = await fetchAndDetectDefault(basePath, git);
+    // Try creating a new branch worktree first
+    try {
+        const addArgs = startPoint
+            ? ["worktree", "add", "-b", branch, wtPath, startPoint]
+            : ["worktree", "add", "-b", branch, wtPath];
+        await git.exec(addArgs, { cwd: basePath });
+        return { worktreePath: wtPath, branch, created: true, synced };
+    }
+    catch {
+        // Branch may already exist — try without -b
+        try {
+            await git.exec(["worktree", "add", wtPath, branch], { cwd: basePath });
+            return { worktreePath: wtPath, branch, created: true, synced };
+        }
+        catch (err) {
+            throw new Error(`Failed to create worktree for branch ${branch}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+export async function removeWorktree(basePath, branch, git = NODE_GIT_EXECUTOR) {
+    const wtPath = worktreeDir(basePath, branch);
+    try {
+        await git.exec(["worktree", "remove", wtPath, "--force"], { cwd: basePath });
+    }
+    catch {
+        // Already removed or doesn't exist — that's fine
+    }
+}
+//# sourceMappingURL=worktree.js.map

package/dist/worktree.js.map

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

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@grackle-ai/runtime-sdk",
+  "version": "0.82.2",
+  "description": "Grackle runtime SDK — interfaces, base classes, shared utilities, and runtime installer",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nick-pape/grackle.git",
+    "directory": "packages/runtime-sdk"
+  },
+  "keywords": [
+    "grackle",
+    "runtime",
+    "sdk",
+    "agent"
+  ],
+  "homepage": "https://github.com/nick-pape/grackle#readme",
+  "bugs": {
+    "url": "https://github.com/nick-pape/grackle/issues"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "pino": "^10.3.1",
+    "@grackle-ai/common": "0.82.2"
+  },
+  "devDependencies": {
+    "@rushstack/heft": "1.2.7",
+    "@types/node": "^22.0.0",
+    "vitest": "^3.1.1",
+    "@grackle-ai/heft-rig": "0.0.1"
+  },
+  "scripts": {
+    "build": "heft build --clean",
+    "test": "vitest run",
+    "clean": "heft clean",
+    "_phase:build": "heft run --only build -- --clean",
+    "_phase:test": "vitest run"
+  }
+}