@ai-hero/sandcastle 0.5.0 → 0.5.4

package/dist/mountUtils.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Shared mount utilities for Docker and Podman sandbox providers.
+ *
+ * Handles host/sandbox path resolution, tilde expansion, user mount
+ * validation, image naming, and Windows path normalization.
+ */
+import type { MountConfig } from "./MountConfig.js";
+/**
+ * Deterministic mount point inside the sandbox for the parent repo's .git
+ * directory when the workspace is a git worktree. See ADR-0006.
+ */
+export declare const PARENT_GIT_SANDBOX_DIR = "/.sandcastle-parent-git";
+/**
+ * Derive the default image name from the repo directory.
+ * Returns `sandcastle:<dir-name>` where dir-name is the last path segment,
+ * lowercased and sanitized for image tag rules.
+ *
+ * Handles both POSIX (`/`) and Windows (`\`) path separators.
+ */
+export declare const defaultImageName: (repoDir: string) => string;
+/**
+ * Expand tilde (`~`) to the given home directory (or `os.homedir()` if omitted).
+ * Handles both `~/path` (POSIX) and `~\path` (Windows).
+ */
+export declare const expandTilde: (p: string, homeDirPath?: string | undefined) => string;
+/**
+ * Resolve a host path: expand tilde, then resolve relative paths from `process.cwd()`.
+ */
+export declare const resolveHostPath: (hostPath: string) => string;
+/**
+ * Resolve a sandbox path: expands tilde using `sandboxHomedir`, then resolves
+ * relative paths from `SANDBOX_REPO_DIR`.
+ *
+ * Throws if `sandboxPath` starts with `~` but `sandboxHomedir` is `undefined`.
+ */
+export declare const resolveSandboxPath: (sandboxPath: string, sandboxHomedir?: string | undefined) => string;
+/**
+ * Resolve and validate user-provided mount configurations.
+ * Throws if a hostPath does not exist on the filesystem.
+ * Throws if a sandboxPath uses tilde but `sandboxHomedir` is `undefined`.
+ */
+export declare const resolveUserMounts: (mounts: readonly MountConfig[], sandboxHomedir?: string | undefined) => {
+    hostPath: string;
+    sandboxPath: string;
+    readonly?: boolean | undefined;
+}[];
+/**
+ * Normalize mount entries for cross-platform compatibility.
+ *
+ * On Windows (`platform === "win32"`):
+ * - Replaces backslashes with forward slashes in all `hostPath` values
+ * - Remaps `sandboxPath` values that look like Windows paths to valid POSIX
+ *   paths relative to `sandboxRepoDir` when the host path is under the
+ *   worktree host path
+ *
+ * On non-Windows platforms, returns mounts unchanged (preserving
+ * `sandboxPath === hostPath` for git mounts so that `gitdir:` references
+ * resolve correctly inside the container).
+ *
+ * This is a pure function — no filesystem access, accepts a `platform`
+ * parameter so it can be unit-tested with fake Windows paths.
+ */
+export declare const normalizeMounts: <M extends {
+    hostPath: string;
+    sandboxPath: string;
+}>(mounts: M[], worktreeHostPath: string, sandboxRepoDir: string, platform?: string) => M[];
+/**
+ * Parse a `gitdir:` path into its parent .git directory and worktree name.
+ *
+ * The gitdir path is like `/path/to/repo/.git/worktrees/<name>` or
+ * `C:\Users\project\.git\worktrees\<name>`. We split on both `/` and `\`
+ * so this works regardless of the host platform or which platform runs tests.
+ */
+export declare const parseGitdirPath: (gitdirPath: string) => {
+    parentGitDir: string;
+    worktreeName: string;
+};
+/**
+ * On Windows, patch git mounts so that worktree `.git` files resolve inside
+ * the Linux sandbox. See ADR-0006 for the full rationale.
+ *
+ * Two fixes are applied:
+ * 1. The parent `.git` directory mount is remapped to `PARENT_GIT_SANDBOX_DIR`.
+ * 2. A corrected `.git` file (with a POSIX `gitdir:` path) is created and
+ *    mounted at `sandboxRepoDir/.git`, overlaying the original.
+ *
+ * On non-Windows platforms, or when the worktree's `.git` is a directory
+ * (not a worktree pointer), returns the mounts unchanged.
+ *
+ * @param gitMounts - Raw mounts from `resolveGitMounts`.
+ * @param worktreeHostPath - Host path to the directory mounted at `sandboxRepoDir`.
+ * @param sandboxRepoDir - Where the worktree is mounted inside the sandbox.
+ * @param readFile - Read a file's content (injectable for tests).
+ * @param statFile - Stat a file to check if it's a directory (injectable for tests).
+ * @param platform - Override for `process.platform` (injectable for tests).
+ */
+export declare const patchGitMountsForWindows: (gitMounts: {
+    hostPath: string;
+    sandboxPath: string;
+}[], worktreeHostPath: string, sandboxRepoDir: string, readFile?: ((path: string) => Promise<string>) | undefined, statFile?: ((path: string) => Promise<"directory" | "file">) | undefined, platform?: string) => Promise<{
+    hostPath: string;
+    sandboxPath: string;
+}[]>;
+//# sourceMappingURL=mountUtils.d.ts.map

package/dist/mountUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mountUtils.d.ts","sourceRoot":"","sources":["../src/mountUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD;;;GAGG;AACH,eAAO,MAAM,sBAAsB,4BAA4B,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,6BAQ5B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,yDAKvB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,8BAG3B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,sEAiB9B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;GAqB1B,CAAC;AAEL;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,GAC1B,CAAC;;;2FAuCF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe;;;CAS3B,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,wBAAwB;;;;;;IAwFpC,CAAC"}

package/dist/mountUtils.js

@@ -0,0 +1,245 @@
+/**
+ * Shared mount utilities for Docker and Podman sandbox providers.
+ *
+ * Handles host/sandbox path resolution, tilde expansion, user mount
+ * validation, image naming, and Windows path normalization.
+ */
+import { existsSync } from "node:fs";
+import { tmpdir, homedir } from "node:os";
+import { isAbsolute, resolve, join } from "node:path";
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { SANDBOX_REPO_DIR } from "./SandboxFactory.js";
+/**
+ * Deterministic mount point inside the sandbox for the parent repo's .git
+ * directory when the workspace is a git worktree. See ADR-0006.
+ */
+export const PARENT_GIT_SANDBOX_DIR = "/.sandcastle-parent-git";
+/**
+ * Derive the default image name from the repo directory.
+ * Returns `sandcastle:<dir-name>` where dir-name is the last path segment,
+ * lowercased and sanitized for image tag rules.
+ *
+ * Handles both POSIX (`/`) and Windows (`\`) path separators.
+ */
+export const defaultImageName = (repoDir) => {
+    const dirName = repoDir
+        .replace(/[\\/]+$/, "")
+        .split(/[\\/]/)
+        .pop() ?? "local";
+    const sanitized = dirName.toLowerCase().replace(/[^a-z0-9_.-]/g, "-");
+    return `sandcastle:${sanitized || "local"}`;
+};
+/**
+ * Expand tilde (`~`) to the given home directory (or `os.homedir()` if omitted).
+ * Handles both `~/path` (POSIX) and `~\path` (Windows).
+ */
+export const expandTilde = (p, homeDirPath) => {
+    const home = homeDirPath ?? homedir();
+    if (p === "~")
+        return home;
+    if (p.startsWith("~/") || p.startsWith("~\\"))
+        return home + "/" + p.slice(2);
+    return p;
+};
+/**
+ * Resolve a host path: expand tilde, then resolve relative paths from `process.cwd()`.
+ */
+export const resolveHostPath = (hostPath) => {
+    const expanded = expandTilde(hostPath);
+    return isAbsolute(expanded) ? expanded : resolve(process.cwd(), expanded);
+};
+/**
+ * Resolve a sandbox path: expands tilde using `sandboxHomedir`, then resolves
+ * relative paths from `SANDBOX_REPO_DIR`.
+ *
+ * Throws if `sandboxPath` starts with `~` but `sandboxHomedir` is `undefined`.
+ */
+export const resolveSandboxPath = (sandboxPath, sandboxHomedir) => {
+    const hasTilde = sandboxPath === "~" ||
+        sandboxPath.startsWith("~/") ||
+        sandboxPath.startsWith("~\\");
+    if (hasTilde && sandboxHomedir === undefined) {
+        throw new Error(`sandboxPath "${sandboxPath}" contains a tilde but the provider has no sandboxHomedir set`);
+    }
+    const expanded = hasTilde
+        ? expandTilde(sandboxPath, sandboxHomedir)
+        : sandboxPath;
+    return isAbsolute(expanded) ? expanded : resolve(SANDBOX_REPO_DIR, expanded);
+};
+/**
+ * Resolve and validate user-provided mount configurations.
+ * Throws if a hostPath does not exist on the filesystem.
+ * Throws if a sandboxPath uses tilde but `sandboxHomedir` is `undefined`.
+ */
+export const resolveUserMounts = (mounts, sandboxHomedir) => mounts.map((m) => {
+    const resolvedHostPath = resolveHostPath(m.hostPath);
+    if (!existsSync(resolvedHostPath)) {
+        throw new Error(`Mount hostPath does not exist: ${m.hostPath}` +
+            (m.hostPath !== resolvedHostPath
+                ? ` (resolved to ${resolvedHostPath})`
+                : ""));
+    }
+    return {
+        hostPath: resolvedHostPath,
+        sandboxPath: resolveSandboxPath(m.sandboxPath, sandboxHomedir),
+        ...(m.readonly ? { readonly: true } : {}),
+    };
+});
+/**
+ * Normalize mount entries for cross-platform compatibility.
+ *
+ * On Windows (`platform === "win32"`):
+ * - Replaces backslashes with forward slashes in all `hostPath` values
+ * - Remaps `sandboxPath` values that look like Windows paths to valid POSIX
+ *   paths relative to `sandboxRepoDir` when the host path is under the
+ *   worktree host path
+ *
+ * On non-Windows platforms, returns mounts unchanged (preserving
+ * `sandboxPath === hostPath` for git mounts so that `gitdir:` references
+ * resolve correctly inside the container).
+ *
+ * This is a pure function — no filesystem access, accepts a `platform`
+ * parameter so it can be unit-tested with fake Windows paths.
+ */
+export const normalizeMounts = (mounts, worktreeHostPath, sandboxRepoDir, platform = process.platform) => {
+    if (platform !== "win32")
+        return mounts;
+    const normalizedWorktree = worktreeHostPath.replace(/\\/g, "/");
+    return mounts.map((m) => {
+        const hostPath = m.hostPath.replace(/\\/g, "/");
+        let sandboxPath = m.sandboxPath;
+        // If sandboxPath is already a valid POSIX absolute path (e.g., user-specified
+        // sandbox paths like /mnt/data or /home/agent/workspace), leave it as-is.
+        // Otherwise, normalize it — Windows-style sandboxPaths (from resolveGitMounts
+        // setting sandboxPath === hostPath) need remapping.
+        if (/^[A-Za-z]:[/\\]/.test(sandboxPath) || sandboxPath.includes("\\")) {
+            // This is a Windows-style path — remap it
+            const normalizedSandboxPath = sandboxPath.replace(/\\/g, "/");
+            if (normalizedSandboxPath.startsWith(normalizedWorktree + "/")) {
+                // Under the worktree: derive sandbox path relative to sandboxRepoDir
+                const relativeSuffix = normalizedSandboxPath.slice(normalizedWorktree.length);
+                sandboxPath = sandboxRepoDir + relativeSuffix;
+            }
+            else if (normalizedSandboxPath === normalizedWorktree) {
+                sandboxPath = sandboxRepoDir;
+            }
+            else {
+                // Not under the worktree — just normalize slashes
+                sandboxPath = normalizedSandboxPath;
+            }
+        }
+        return { ...m, hostPath, sandboxPath };
+    });
+};
+/**
+ * Parse a `gitdir:` path into its parent .git directory and worktree name.
+ *
+ * The gitdir path is like `/path/to/repo/.git/worktrees/<name>` or
+ * `C:\Users\project\.git\worktrees\<name>`. We split on both `/` and `\`
+ * so this works regardless of the host platform or which platform runs tests.
+ */
+export const parseGitdirPath = (gitdirPath) => {
+    const normalized = gitdirPath.replace(/\\/g, "/").replace(/\/+$/, "");
+    const segments = normalized.split("/");
+    const worktreeName = segments.pop(); // <name>
+    segments.pop(); // "worktrees"
+    const parentGitDir = segments.join("/");
+    return { worktreeName, parentGitDir };
+};
+/**
+ * On Windows, patch git mounts so that worktree `.git` files resolve inside
+ * the Linux sandbox. See ADR-0006 for the full rationale.
+ *
+ * Two fixes are applied:
+ * 1. The parent `.git` directory mount is remapped to `PARENT_GIT_SANDBOX_DIR`.
+ * 2. A corrected `.git` file (with a POSIX `gitdir:` path) is created and
+ *    mounted at `sandboxRepoDir/.git`, overlaying the original.
+ *
+ * On non-Windows platforms, or when the worktree's `.git` is a directory
+ * (not a worktree pointer), returns the mounts unchanged.
+ *
+ * @param gitMounts - Raw mounts from `resolveGitMounts`.
+ * @param worktreeHostPath - Host path to the directory mounted at `sandboxRepoDir`.
+ * @param sandboxRepoDir - Where the worktree is mounted inside the sandbox.
+ * @param readFile - Read a file's content (injectable for tests).
+ * @param statFile - Stat a file to check if it's a directory (injectable for tests).
+ * @param platform - Override for `process.platform` (injectable for tests).
+ */
+export const patchGitMountsForWindows = async (gitMounts, worktreeHostPath, sandboxRepoDir, readFile, statFile, platform = process.platform) => {
+    if (platform !== "win32")
+        return gitMounts;
+    const _readFile = readFile ??
+        (async (p) => {
+            const { readFile: rf } = await import("node:fs/promises");
+            return rf(p, "utf-8");
+        });
+    const _statFile = statFile ??
+        (async (p) => {
+            const { stat } = await import("node:fs/promises");
+            const s = await stat(p);
+            return s.isDirectory() ? "directory" : "file";
+        });
+    // Check the worktree's .git entry
+    const gitEntryPath = join(worktreeHostPath, ".git");
+    let gitEntryType;
+    try {
+        gitEntryType = await _statFile(gitEntryPath);
+    }
+    catch {
+        return gitMounts;
+    }
+    if (gitEntryType === "directory")
+        return gitMounts;
+    // Read and parse the gitdir: line
+    let content;
+    try {
+        content = (await _readFile(gitEntryPath)).trim();
+    }
+    catch {
+        return gitMounts;
+    }
+    const match = content.match(/^gitdir:\s*(.+)$/);
+    if (!match)
+        return gitMounts;
+    const gitdirPath = match[1];
+    const { parentGitDir, worktreeName } = parseGitdirPath(gitdirPath);
+    // Create a temp file with the corrected gitdir content
+    const correctedGitdir = `${PARENT_GIT_SANDBOX_DIR}/worktrees/${worktreeName}`;
+    const tempDir = await mkdtemp(join(tmpdir(), "sandcastle-git-"));
+    const tempGitFile = join(tempDir, "git-override");
+    await writeFile(tempGitFile, `gitdir: ${correctedGitdir}\n`);
+    // Build corrected mounts
+    const normalizedParentGitDir = parentGitDir.replace(/\\/g, "/");
+    const gitFileHostPath = gitEntryPath.replace(/\\/g, "/");
+    const correctedMounts = [];
+    let replacedGitFile = false;
+    for (const m of gitMounts) {
+        const normalizedHostPath = m.hostPath.replace(/\\/g, "/");
+        if (normalizedHostPath === normalizedParentGitDir) {
+            // Remap parent .git dir to deterministic sandbox path
+            correctedMounts.push({ ...m, sandboxPath: PARENT_GIT_SANDBOX_DIR });
+        }
+        else if (normalizedHostPath === gitFileHostPath) {
+            // Replace .git file mount with corrected version (host repo is a worktree)
+            correctedMounts.push({
+                ...m,
+                hostPath: tempGitFile,
+                sandboxPath: `${sandboxRepoDir}/.git`,
+            });
+            replacedGitFile = true;
+        }
+        else {
+            correctedMounts.push(m);
+        }
+    }
+    // If the .git file wasn't in gitMounts (Sandcastle-created worktree),
+    // add an overlay mount for the corrected .git file
+    if (!replacedGitFile) {
+        correctedMounts.push({
+            hostPath: tempGitFile,
+            sandboxPath: `${sandboxRepoDir}/.git`,
+        });
+    }
+    return correctedMounts;
+};
+//# sourceMappingURL=mountUtils.js.map

package/dist/mountUtils.js.map

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

package/dist/raceAbortSignal.d.ts

@@ -0,0 +1,18 @@
+import { Effect } from "effect";
+/**
+ * Race an Effect against an optional `AbortSignal`.
+ *
+ * - If no signal is provided, the effect runs unmodified.
+ * - If the signal is already aborted at call time, dies immediately with
+ *   `signal.reason`.
+ * - Otherwise, races the effect against a Deferred that fires when the
+ *   signal aborts.
+ *
+ * Uses `Effect.die` so the abort reason propagates as a defect — callers
+ * should use `signal.throwIfAborted()` in their catch handler to surface
+ * the original reason without Sandcastle-specific wrapping.
+ *
+ * The abort listener is always cleaned up, even when the effect wins the race.
+ */
+export declare const raceAbortSignal: <A, E, R>(effect: Effect.Effect<A, E, R>, signal?: AbortSignal | undefined) => Effect.Effect<A, E, R>;
+//# sourceMappingURL=raceAbortSignal.d.ts.map

package/dist/raceAbortSignal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raceAbortSignal.d.ts","sourceRoot":"","sources":["../src/raceAbortSignal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,MAAM,EAAE,MAAM,QAAQ,CAAC;AAE1C;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,6FA4BtC,CAAC"}

package/dist/raceAbortSignal.js

@@ -0,0 +1,32 @@
+import { Deferred, Effect } from "effect";
+/**
+ * Race an Effect against an optional `AbortSignal`.
+ *
+ * - If no signal is provided, the effect runs unmodified.
+ * - If the signal is already aborted at call time, dies immediately with
+ *   `signal.reason`.
+ * - Otherwise, races the effect against a Deferred that fires when the
+ *   signal aborts.
+ *
+ * Uses `Effect.die` so the abort reason propagates as a defect — callers
+ * should use `signal.throwIfAborted()` in their catch handler to surface
+ * the original reason without Sandcastle-specific wrapping.
+ *
+ * The abort listener is always cleaned up, even when the effect wins the race.
+ */
+export const raceAbortSignal = (effect, signal) => {
+    if (!signal)
+        return effect;
+    return Effect.gen(function* () {
+        if (signal.aborted) {
+            return yield* Effect.die(signal.reason);
+        }
+        const abortDeferred = yield* Deferred.make();
+        const onAbort = () => {
+            Effect.runPromise(Deferred.die(abortDeferred, signal.reason)).catch(() => { });
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        return yield* Effect.raceFirst(effect, Deferred.await(abortDeferred)).pipe(Effect.ensuring(Effect.sync(() => signal.removeEventListener("abort", onAbort))));
+    });
+};
+//# sourceMappingURL=raceAbortSignal.js.map

package/dist/raceAbortSignal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"raceAbortSignal.js","sourceRoot":"","sources":["../src/raceAbortSignal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAE1C;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,MAA8B,EAC9B,MAAoB,EACI,EAAE;IAC1B,IAAI,CAAC,MAAM;QAAE,OAAO,MAAM,CAAC;IAE3B,OAAO,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QACzB,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC1C,CAAC;QAED,MAAM,aAAa,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAgB,CAAC;QAC3D,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CACjE,GAAG,EAAE,GAAE,CAAC,CACT,CAAC;QACJ,CAAC,CAAC;QACF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAE1D,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,SAAS,CAC5B,MAAM,EACN,QAAQ,CAAC,KAAK,CAAC,aAAa,CAAuC,CACpE,CAAC,IAAI,CACJ,MAAM,CAAC,QAAQ,CACb,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAChE,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC,CAAC"}

package/dist/resolveCwd.d.ts

@@ -0,0 +1,24 @@
+import { FileSystem } from "@effect/platform";
+import { Effect } from "effect";
+declare const CwdError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "CwdError";
+} & Readonly<A>;
+/** The provided `cwd` path does not exist or is not a directory. */
+export declare class CwdError extends CwdError_base<{
+    readonly message: string;
+    readonly cwd: string;
+}> {
+}
+/**
+ * Resolve an optional `cwd` string to an absolute, validated host repo directory.
+ *
+ * - `undefined` → `process.cwd()` (resolved to absolute).
+ * - Relative path → resolved against `process.cwd()`.
+ * - Absolute path → passed through.
+ *
+ * Stats the result via Effect's `FileSystem`; fails with {@link CwdError}
+ * when the path is missing or is not a directory.
+ */
+export declare const resolveCwd: (cwd: string | undefined) => Effect.Effect<string, CwdError, FileSystem.FileSystem>;
+export {};
+//# sourceMappingURL=resolveCwd.d.ts.map

package/dist/resolveCwd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveCwd.d.ts","sourceRoot":"","sources":["../src/resolveCwd.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAQ,MAAM,EAAE,MAAM,QAAQ,CAAC;;;;AAEtC,oEAAoE;AACpE,qBAAa,QAAS,SAAQ,cAA6B;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB,CAAC;CAAG;AAEL;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,qFA0BnB,CAAC"}

package/dist/resolveCwd.js

@@ -0,0 +1,32 @@
+import { FileSystem } from "@effect/platform";
+import { resolve } from "node:path";
+import { Data, Effect } from "effect";
+/** The provided `cwd` path does not exist or is not a directory. */
+export class CwdError extends Data.TaggedError("CwdError") {
+}
+/**
+ * Resolve an optional `cwd` string to an absolute, validated host repo directory.
+ *
+ * - `undefined` → `process.cwd()` (resolved to absolute).
+ * - Relative path → resolved against `process.cwd()`.
+ * - Absolute path → passed through.
+ *
+ * Stats the result via Effect's `FileSystem`; fails with {@link CwdError}
+ * when the path is missing or is not a directory.
+ */
+export const resolveCwd = (cwd) => Effect.gen(function* () {
+    const resolved = cwd !== undefined ? resolve(process.cwd(), cwd) : resolve(process.cwd());
+    const fs = yield* FileSystem.FileSystem;
+    const stat = yield* fs.stat(resolved).pipe(Effect.mapError(() => new CwdError({
+        message: `cwd does not exist: ${resolved}`,
+        cwd: resolved,
+    })));
+    if (stat.type !== "Directory") {
+        return yield* new CwdError({
+            message: `cwd is not a directory: ${resolved}`,
+            cwd: resolved,
+        });
+    }
+    return resolved;
+});
+//# sourceMappingURL=resolveCwd.js.map

package/dist/resolveCwd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveCwd.js","sourceRoot":"","sources":["../src/resolveCwd.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEtC,oEAAoE;AACpE,MAAM,OAAO,QAAS,SAAQ,IAAI,CAAC,WAAW,CAAC,UAAU,CAGvD;CAAG;AAEL;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CACxB,GAAuB,EACiC,EAAE,CAC1D,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,QAAQ,GACZ,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAE3E,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC;IAExC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CACxC,MAAM,CAAC,QAAQ,CACb,GAAG,EAAE,CACH,IAAI,QAAQ,CAAC;QACX,OAAO,EAAE,uBAAuB,QAAQ,EAAE;QAC1C,GAAG,EAAE,QAAQ;KACd,CAAC,CACL,CACF,CAAC;IACF,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC,CAAC,IAAI,QAAQ,CAAC;YACzB,OAAO,EAAE,2BAA2B,QAAQ,EAAE;YAC9C,GAAG,EAAE,QAAQ;SACd,CAAC,CAAC;IACL,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/run.d.ts

@@ -1,7 +1,8 @@
 import type { AgentProvider } from "./AgentProvider.js";
 import { type Severity } from "./Display.js";
-import { type IterationResult } from "./Orchestrator.js";
+import { type IterationResult, type IterationUsage } from "./Orchestrator.js";
 import type { SandboxProvider, BranchStrategy } from "./SandboxProvider.js";
+import { type AgentStreamEvent } from "./AgentStreamEmitter.js";
 import type { SandboxHooks } from "./SandboxLifecycle.js";
 import { type PromptArgs } from "./PromptArgumentSubstitution.js";
 /** Default maximum number of iterations for a run. */
@@ -12,6 +13,11 @@ export interface FileDisplayStartupOptions {
     readonly logPath: string;
     readonly agentName?: string;
     readonly branch?: string;
+    /** Resolved host repo directory. When it differs from `process.cwd()`, the
+     *  log-file hint is printed as an absolute path so it can be pasted into any
+     *  terminal. When it equals `process.cwd()` (or is omitted), a relative path
+     *  is printed instead. */
+    readonly hostRepoDir?: string;
 }
 /**
  * Print the startup message to the terminal when using file-based logging.
@@ -48,6 +54,18 @@ export declare const buildCompletionMessage: (completionSignal: string | undefin
     readonly message: string;
     readonly severity: Severity;
 };
+/**
+ * Format the context window size from an iteration's usage data.
+ * Returns a string like "103k" representing the total input-side tokens
+ * (inputTokens + cacheCreationInputTokens + cacheReadInputTokens)
+ * rounded up to the nearest 1000.
+ */
+export declare const formatContextWindowSize: (usage: IterationUsage) => string;
+/**
+ * Build "Context window: NNNk" lines for iterations that have usage data.
+ * Returns an empty array when no iterations carry usage.
+ */
+export declare const buildContextWindowLines: (iterations: readonly Pick<IterationResult, "usage">[]) => string[];
 /**
  * Controls where Sandcastle writes iteration progress and agent output.
  * Use `"file"` (log-to-file mode) to write to a log file on disk, or
@@ -58,6 +76,13 @@ export type LoggingOption =
 {
     readonly type: "file";
     readonly path: string;
+    /**
+     * Optional callback invoked for each agent stream event (text chunk or
+     * tool call) in addition to being written to the log file. Intended for
+     * forwarding the agent's output stream to external observability
+     * systems. Errors thrown by the callback are swallowed.
+     */
+    readonly onAgentStreamEvent?: (event: AgentStreamEvent) => void;
 }
 /** Render progress and agent output as an interactive UI in the terminal (terminal mode). */
  | {
@@ -68,9 +93,25 @@ export interface RunOptions {
     readonly agent: AgentProvider;
     /** Sandbox provider (e.g. docker({ imageName: "sandcastle:myrepo" })). */
     readonly sandbox: SandboxProvider;
+    /**
+     * Host repo directory. Replaces `process.cwd()` as the anchor for
+     * `.sandcastle/worktrees/`, `.sandcastle/.env`, `.sandcastle/logs/`,
+     * `.sandcastle/patches/`, and git operations.
+     *
+     * - Relative paths are resolved against `process.cwd()`.
+     * - Absolute paths are used as-is.
+     * - Defaults to `process.cwd()` when omitted.
+     */
+    readonly cwd?: string;
     /** Inline prompt string (mutually exclusive with promptFile) */
     readonly prompt?: string;
-    /** Path to a prompt file (mutually exclusive with prompt) */
+    /**
+     * Path to a prompt file (mutually exclusive with prompt).
+     *
+     * **Note:** `promptFile` is always resolved against `process.cwd()`, not
+     * against the `cwd` option. If you set a custom `cwd`, pass an absolute
+     * `promptFile` to avoid ambiguity.
+     */
     readonly promptFile?: string;
     /** Maximum iterations to run (default: 1) */
     readonly maxIterations?: number;
@@ -91,12 +132,22 @@ export interface RunOptions {
     /** Branch strategy — controls how the agent's changes relate to branches.
      * Defaults to { type: "head" } for bind-mount providers and { type: "merge-to-head" } for isolated providers. */
     readonly branchStrategy?: BranchStrategy;
-    /** When false, reuse an existing worktree for the target branch instead of failing on collision. Default: true. */
-    readonly throwOnDuplicateWorktree?: boolean;
     /** Resume a prior Claude Code session by ID. The session JSONL must exist on the host. Incompatible with maxIterations > 1. */
     readonly resumeSession?: string;
+    /**
+     * An `AbortSignal` that cancels the run when aborted.
+     *
+     * - If `signal.aborted` is already `true` at entry, `run()` rejects
+     *   immediately without doing any setup work.
+     * - Aborting mid-iteration kills the in-flight agent subprocess.
+     * - Phase boundaries (between iterations) also check the signal.
+     * - The rejected promise surfaces `signal.reason` via
+     *   `signal.throwIfAborted()` — no Sandcastle-specific wrapping.
+     * - The worktree is preserved on disk after abort (error-path behavior).
+     */
+    readonly signal?: AbortSignal;
 }
-export type { IterationResult } from "./Orchestrator.js";
+export type { IterationResult, IterationUsage } from "./Orchestrator.js";
 export interface RunResult {
     /** Per-iteration results (use `iterations.length` for the count). */
     readonly iterations: IterationResult[];

package/dist/run.d.ts.map

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