@yadsh/dsh-session-scope 0.5.0

package/lib/scope-sandbox-linux.js

@@ -0,0 +1,177 @@
+import { spawnSync } from "node:child_process";
+import { posix } from "node:path";
+import { SESSION_SCOPE_ERROR, SessionScopeError, } from "./session-scope.js";
+/** Same-world, non-serialized carrier added to DSH's per-call sandbox policy. */
+export const SESSION_SCOPE_POLICY = Symbol.for("dsh-session-scope/policy");
+const BWRAP_READ_ONLY_PROFILE = [
+    "bwrap",
+    "--ro-bind", "/", "/",
+    "--dev", "/dev",
+    "--proc", "/proc",
+    "--die-with-parent",
+];
+const BWRAP_STAGING_ROOT = "/dev/.dsh-session-scope";
+function unavailable(detail) {
+    throw new SessionScopeError(SESSION_SCOPE_ERROR.ISOLATION_UNAVAILABLE, `Isolated session scope is unavailable: ${detail}.`);
+}
+function normalizedAbsolute(path, label) {
+    if (!posix.isAbsolute(path) || path.includes("\0"))
+        unavailable(`invalid ${label}`);
+    return posix.normalize(path);
+}
+function sameArray(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function expectedProfile(policy) {
+    if (policy.mode === "read-only")
+        return [...BWRAP_READ_ONLY_PROFILE];
+    if (policy.mode === "workspace-write") {
+        return [
+            ...BWRAP_READ_ONLY_PROFILE,
+            "--tmpfs", "/tmp",
+            "--bind", policy.workspaceRoot, policy.workspaceRoot,
+        ];
+    }
+    return unavailable("the active permission mode cannot be confined by the DSH bwrap provider");
+}
+function separatorIndex(argv) {
+    const index = argv.indexOf("--");
+    if (index < 0 || index === argv.length - 1)
+        unavailable("the sandbox provider returned an invalid bwrap invocation");
+    return index;
+}
+/** Require the exact, versioned DSH bwrap profile this plugin knows how to narrow. */
+export function isSupportedBwrapInvocation(confined, policy) {
+    if (confined.enforcement !== "full")
+        return false;
+    try {
+        const separator = separatorIndex(confined.argv);
+        return sameArray(confined.argv.slice(0, separator), expectedProfile(policy));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Probe the official provider seam. The local provider performs its own
+ * functional bwrap probe before returning this direct profile.
+ */
+export function detectBwrapIsolation(provider, workspaceRoot, platform = process.platform, execute = (argv) => {
+    const result = spawnSync(argv[0], argv.slice(1), { stdio: "ignore", timeout: 5_000 });
+    return result.error === undefined && result.status === 0;
+}) {
+    if (platform !== "linux" || provider === undefined)
+        return false;
+    try {
+        const policy = { mode: "read-only", workspaceRoot };
+        const confined = provider.confine(["true"], policy);
+        if (!isSupportedBwrapInvocation(confined, policy))
+            return false;
+        const probe = confineIsolatedBwrap(confined, policy, {
+            mode: "isolated",
+            workspaceRoot,
+            roots: [],
+            navigationRoots: [workspaceRoot],
+        }, workspaceRoot);
+        return execute(probe.argv);
+    }
+    catch {
+        return false;
+    }
+}
+function isWithin(path, root) {
+    return path === root || path.startsWith(root === "/" ? "/" : `${root}/`);
+}
+function visibleWorkingDirectory(requested, workspaceRoot, roots) {
+    const workdir = normalizedAbsolute(requested === undefined ? workspaceRoot : posix.resolve(workspaceRoot, requested), "process working directory");
+    if (!isWithin(workdir, workspaceRoot))
+        unavailable("the process working directory is outside the session workspace");
+    const content = roots.some((root) => isWithin(workdir, root));
+    const navigation = workdir === workspaceRoot || roots.some((root) => isWithin(root, workdir));
+    if (!content && !navigation)
+        unavailable("the process working directory is outside the active session scope");
+    return workdir;
+}
+function mountPointDirectories(workspaceRoot, roots) {
+    const result = [];
+    const seen = new Set();
+    for (const root of roots) {
+        if (root === workspaceRoot)
+            continue;
+        const relative = posix.relative(workspaceRoot, root);
+        let current = workspaceRoot;
+        for (const segment of relative.split("/").filter(Boolean)) {
+            current = posix.join(current, segment);
+            if (!seen.has(current)) {
+                seen.add(current);
+                result.push(current);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Replace DSH's whole-workspace bwrap view with an empty workspace plus only
+ * the selected roots. Unknown argv dialects and partial enforcement fail closed.
+ */
+export function confineIsolatedBwrap(confined, policy, scope, requestedWorkingDirectory) {
+    if (scope.mode !== "isolated")
+        return confined;
+    if (confined.enforcement !== "full")
+        unavailable("the selected sandbox backend reports partial enforcement");
+    const workspaceRoot = normalizedAbsolute(scope.workspaceRoot, "session workspace");
+    if (workspaceRoot === "/")
+        unavailable("the filesystem root cannot be used as an isolated workspace");
+    if (isWithin(workspaceRoot, "/dev"))
+        unavailable("a workspace under /dev cannot be isolated safely");
+    if (normalizedAbsolute(policy.workspaceRoot, "sandbox workspace") !== workspaceRoot) {
+        unavailable("the sandbox and session workspace boundaries do not match");
+    }
+    if (!isSupportedBwrapInvocation(confined, policy)) {
+        unavailable("the sandbox provider is not the supported DSH bwrap profile");
+    }
+    const roots = scope.roots.map((root) => normalizedAbsolute(root, "scope root"));
+    if (roots.some((root) => !isWithin(root, workspaceRoot)))
+        unavailable("a selected root is outside the session workspace");
+    const workdir = visibleWorkingDirectory(requestedWorkingDirectory, workspaceRoot, roots);
+    const separator = separatorIndex(confined.argv);
+    const command = confined.argv.slice(separator + 1);
+    // Selecting the workspace root means the requested visible view is already
+    // the whole workspace. Still pin cwd after bwrap establishes its mounts.
+    if (roots.includes(workspaceRoot)) {
+        return {
+            ...confined,
+            argv: [...confined.argv.slice(0, separator), "--chdir", workdir, "--", ...command],
+        };
+    }
+    const profile = confined.argv.slice(0, separator);
+    if (policy.mode === "workspace-write")
+        profile.splice(profile.length - 3, 3);
+    const bindFlag = policy.mode === "workspace-write" ? "--bind" : "--ro-bind";
+    const mounts = ["--dir", BWRAP_STAGING_ROOT, "--tmpfs", BWRAP_STAGING_ROOT];
+    for (let index = 0; index < roots.length; index += 1) {
+        const staging = `${BWRAP_STAGING_ROOT}/${index}`;
+        mounts.push("--dir", staging, bindFlag, roots[index], staging);
+    }
+    mounts.push("--tmpfs", workspaceRoot);
+    for (const directory of mountPointDirectories(workspaceRoot, roots))
+        mounts.push("--dir", directory);
+    for (let index = 0; index < roots.length; index += 1) {
+        mounts.push(bindFlag, `${BWRAP_STAGING_ROOT}/${index}`, roots[index]);
+    }
+    // Drop the alternate path to selected content and leave no new writable
+    // scratch area behind, including under read-only permission.
+    mounts.push("--tmpfs", BWRAP_STAGING_ROOT, "--remount-ro", BWRAP_STAGING_ROOT);
+    return {
+        ...confined,
+        argv: [...profile, ...mounts, "--chdir", workdir, "--", ...command],
+    };
+}
+/** Attach the effective scope without changing DSH's public policy shape. */
+export function attachSessionScopePolicy(policy, scope) {
+    return Object.assign({}, policy, { [SESSION_SCOPE_POLICY]: scope });
+}
+export function sessionScopeFromPolicy(policy) {
+    return policy[SESSION_SCOPE_POLICY];
+}
+//# sourceMappingURL=scope-sandbox-linux.js.map

package/lib/scope-sandbox-linux.js.map

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

package/lib/scope-visibility.d.ts

@@ -0,0 +1,14 @@
+import type { DirectoryListing } from "./core.js";
+import { type EffectiveSessionScope } from "./session-scope.js";
+export type ScopePathVisibility = "content" | "navigation" | "denied";
+export type ScopedFilesystemOperation = "read" | "write" | "list" | "search";
+export declare function classifyScopePath(scope: EffectiveSessionScope, target: string, caseSensitive?: boolean): ScopePathVisibility;
+export declare function assertScopeAccess(scope: EffectiveSessionScope, target: string, operation: ScopedFilesystemOperation, caseSensitive?: boolean): ScopePathVisibility;
+/** Filter a one-level listing without disclosing hidden sibling names. */
+export declare function filterScopeDirectoryListing(scope: EffectiveSessionScope, listing: DirectoryListing, caseSensitive?: boolean): DirectoryListing;
+/**
+ * Reduce a glob/grep/search request to content roots. Callers execute one
+ * search per returned root and merge results; an empty array is a denial.
+ */
+export declare function scopedSearchRoots(scope: EffectiveSessionScope, requestedRoot: string, caseSensitive?: boolean): string[];
+//# sourceMappingURL=scope-visibility.d.ts.map

package/lib/scope-visibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-visibility.d.ts","sourceRoot":"","sources":["../src/scope-visibility.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElE,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,oBAAoB,CAAC;AAE5B,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,YAAY,GAAG,QAAQ,CAAC;AACtE,MAAM,MAAM,yBAAyB,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAM7E,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,qBAAqB,EAC5B,MAAM,EAAE,MAAM,EACd,aAAa,UAA+B,GAC3C,mBAAmB,CAQrB;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,qBAAqB,EAC5B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,yBAAyB,EACpC,aAAa,UAA+B,GAC3C,mBAAmB,CAUrB;AAaD,0EAA0E;AAC1E,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,qBAAqB,EAC5B,OAAO,EAAE,gBAAgB,EACzB,aAAa,UAA+B,GAC3C,gBAAgB,CAUlB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,qBAAqB,EAC5B,aAAa,EAAE,MAAM,EACrB,aAAa,UAA+B,GAC3C,MAAM,EAAE,CAgBV"}

package/lib/scope-visibility.js

@@ -0,0 +1,62 @@
+import { isLexicallyUnder } from "./core.js";
+import { SESSION_SCOPE_ERROR, SessionScopeError, } from "./session-scope.js";
+function samePath(left, right, caseSensitive) {
+    return caseSensitive ? left === right : left.toLowerCase() === right.toLowerCase();
+}
+export function classifyScopePath(scope, target, caseSensitive = process.platform !== "win32") {
+    if (scope.mode === "full")
+        return "content";
+    // Scope narrows only the session workspace. OS/user paths outside it remain
+    // governed by the ordinary DSH permission policy (see the spec non-goals).
+    if (!isLexicallyUnder(target, scope.workspaceRoot, caseSensitive))
+        return "content";
+    if (scope.roots.some((root) => isLexicallyUnder(target, root, caseSensitive)))
+        return "content";
+    if (scope.navigationRoots.some((root) => samePath(target, root, caseSensitive)))
+        return "navigation";
+    return "denied";
+}
+export function assertScopeAccess(scope, target, operation, caseSensitive = process.platform !== "win32") {
+    const visibility = classifyScopePath(scope, target, caseSensitive);
+    const allowed = visibility === "content" || operation === "list" && visibility === "navigation";
+    if (!allowed) {
+        throw new SessionScopeError(SESSION_SCOPE_ERROR.DENIED, "Path is outside the active session scope.");
+    }
+    return visibility;
+}
+function entryLeadsToContent(entry, scope, caseSensitive) {
+    return scope.roots.some((root) => isLexicallyUnder(root, entry.path, caseSensitive)
+        || isLexicallyUnder(entry.path, root, caseSensitive));
+}
+/** Filter a one-level listing without disclosing hidden sibling names. */
+export function filterScopeDirectoryListing(scope, listing, caseSensitive = process.platform !== "win32") {
+    const visibility = assertScopeAccess(scope, listing.path, "list", caseSensitive);
+    if (scope.mode === "full" || visibility === "content")
+        return listing;
+    return {
+        ...listing,
+        crumbs: listing.crumbs.filter((crumb) => classifyScopePath(scope, crumb.path, caseSensitive) !== "denied"),
+        entries: listing.entries.filter((entry) => entryLeadsToContent(entry, scope, caseSensitive)),
+    };
+}
+/**
+ * Reduce a glob/grep/search request to content roots. Callers execute one
+ * search per returned root and merge results; an empty array is a denial.
+ */
+export function scopedSearchRoots(scope, requestedRoot, caseSensitive = process.platform !== "win32") {
+    if (scope.mode === "full")
+        return [requestedRoot];
+    const insideWorkspace = isLexicallyUnder(requestedRoot, scope.workspaceRoot, caseSensitive);
+    const containsWorkspace = isLexicallyUnder(scope.workspaceRoot, requestedRoot, caseSensitive);
+    if (!insideWorkspace && !containsWorkspace)
+        return [requestedRoot];
+    if (scope.roots.some((root) => isLexicallyUnder(requestedRoot, root, caseSensitive))) {
+        return [requestedRoot];
+    }
+    const roots = scope.roots.filter((root) => isLexicallyUnder(root, requestedRoot, caseSensitive));
+    if (roots.length === 0) {
+        throw new SessionScopeError(SESSION_SCOPE_ERROR.DENIED, "Path is outside the active session scope.");
+    }
+    return roots;
+}
+//# sourceMappingURL=scope-visibility.js.map

package/lib/scope-visibility.js.map

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

package/lib/session-scope.d.ts

@@ -0,0 +1,54 @@
+import { type SessionEvent } from "./core.js";
+export declare const SESSION_SCOPE_EVENT: "session-scope/set";
+export declare const SESSION_SCOPE_ERROR: Readonly<{
+    readonly DENIED: "SESSION_SCOPE_DENIED";
+    readonly INVALID_ROOT: "SESSION_SCOPE_INVALID_ROOT";
+    readonly OUTSIDE_WORKSPACE: "SESSION_SCOPE_OUTSIDE_WORKSPACE";
+    readonly SYMLINK_ESCAPE: "SESSION_SCOPE_SYMLINK_ESCAPE";
+    readonly ISOLATION_UNAVAILABLE: "SESSION_SCOPE_ISOLATION_UNAVAILABLE";
+    readonly PROCESS_ACTIVE: "SESSION_SCOPE_PROCESS_ACTIVE";
+    readonly PARENT_UNAVAILABLE: "SESSION_SCOPE_PARENT_UNAVAILABLE";
+    readonly STALE_WORKSPACE: "SESSION_SCOPE_STALE_WORKSPACE";
+}>;
+export type SessionScopeErrorCode = (typeof SESSION_SCOPE_ERROR)[keyof typeof SESSION_SCOPE_ERROR];
+export type SessionScopeMode = "full" | "focused" | "isolated";
+export type SessionScopeSource = "ui" | "command" | "migration" | "delegation";
+export interface SessionScopeEventData {
+    version: 1;
+    mode: SessionScopeMode;
+    roots: string[];
+    workspaceRoot: string;
+    source?: SessionScopeSource;
+}
+export interface SessionHeader {
+    cwd?: string;
+}
+export interface EffectiveSessionScope {
+    mode: SessionScopeMode;
+    workspaceRoot: string;
+    roots: string[];
+    navigationRoots: string[];
+}
+export interface ScopePathServices {
+    canonical(path: string): string;
+    isDirectory(path: string): boolean;
+}
+export interface NormalizeSessionScopeOptions {
+    allowExternalRoots?: boolean;
+    caseSensitive?: boolean;
+    paths?: ScopePathServices;
+}
+export declare class SessionScopeError extends Error {
+    readonly code: SessionScopeErrorCode;
+    constructor(code: SessionScopeErrorCode, message: string);
+}
+/** Drop duplicate and descendant roots already covered by a selected parent. */
+export declare function collapseNestedRoots(roots: readonly string[], caseSensitive?: boolean): string[];
+/** Ancestors visible only for navigation from the workspace to content roots. */
+export declare function navigationRootsFor(workspaceRoot: string, roots: readonly string[], caseSensitive?: boolean): string[];
+/** Validate and canonicalize roots immediately before persisting a snapshot. */
+export declare function normalizeSessionScopeRoots(input: unknown, workspaceRoot: string, options?: NormalizeSessionScopeOptions): string[];
+/** Fold new durable state, falling back to the upstream event only for legacy sessions. */
+export declare function effectiveSessionScope(events: readonly SessionEvent[], sessionHeader?: SessionHeader, caseSensitive?: boolean): EffectiveSessionScope;
+export declare function createSessionScopeEvent(mode: SessionScopeMode, roots: unknown, workspaceRoot: string, source: SessionScopeSource, options?: NormalizeSessionScopeOptions): SessionScopeEventData;
+//# sourceMappingURL=session-scope.d.ts.map

package/lib/session-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-scope.d.ts","sourceRoot":"","sources":["../src/session-scope.ts"],"names":[],"mappings":"AAGA,OAAO,EAML,KAAK,YAAY,EAClB,MAAM,WAAW,CAAC;AAEnB,eAAO,MAAM,mBAAmB,EAAG,mBAA4B,CAAC;AAEhE,eAAO,MAAM,mBAAmB;qBACtB,sBAAsB;2BAChB,4BAA4B;gCACvB,iCAAiC;6BACpC,8BAA8B;oCACvB,qCAAqC;6BAC5C,8BAA8B;iCAC1B,kCAAkC;8BACrC,+BAA+B;EACvC,CAAC;AAEZ,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC;AACnG,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;AAC/D,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,GAAG,YAAY,CAAC;AAE/E,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,CAAC,CAAC;IACX,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,kBAAkB,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,gBAAgB,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CACpC;AAED,MAAM,WAAW,4BAA4B;IAC3C,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,iBAAiB,CAAC;CAC3B;AAgBD,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IAErC,YAAY,IAAI,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,EAIvD;CACF;AAMD,gFAAgF;AAChF,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,aAAa,UAA+B,GAC3C,MAAM,EAAE,CAkBV;AAED,iFAAiF;AACjF,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,aAAa,UAA+B,GAC3C,MAAM,EAAE,CA6BV;AAED,gFAAgF;AAChF,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,EACd,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,4BAAiC,GACzC,MAAM,EAAE,CAgDV;AA6BD,2FAA2F;AAC3F,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,YAAY,EAAE,EAC/B,aAAa,GAAE,aAAkB,EACjC,aAAa,UAA+B,GAC3C,qBAAqB,CA4CvB;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,OAAO,EACd,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,kBAAkB,EAC1B,OAAO,CAAC,EAAE,4BAA4B,GACrC,qBAAqB,CASvB"}

package/lib/session-scope.js

@@ -0,0 +1,200 @@
+import { existsSync, statSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { MAX_ROOTS, SELECTION_EVENT, canonicalPath, isLexicallyUnder, selectionOf, } from "./core.js";
+export const SESSION_SCOPE_EVENT = "session-scope/set";
+export const SESSION_SCOPE_ERROR = Object.freeze({
+    DENIED: "SESSION_SCOPE_DENIED",
+    INVALID_ROOT: "SESSION_SCOPE_INVALID_ROOT",
+    OUTSIDE_WORKSPACE: "SESSION_SCOPE_OUTSIDE_WORKSPACE",
+    SYMLINK_ESCAPE: "SESSION_SCOPE_SYMLINK_ESCAPE",
+    ISOLATION_UNAVAILABLE: "SESSION_SCOPE_ISOLATION_UNAVAILABLE",
+    PROCESS_ACTIVE: "SESSION_SCOPE_PROCESS_ACTIVE",
+    PARENT_UNAVAILABLE: "SESSION_SCOPE_PARENT_UNAVAILABLE",
+    STALE_WORKSPACE: "SESSION_SCOPE_STALE_WORKSPACE",
+});
+const DEFAULT_PATH_SERVICES = {
+    canonical: canonicalPath,
+    isDirectory(path) {
+        if (!existsSync(path))
+            return false;
+        try {
+            return statSync(path).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    },
+};
+const MODES = new Set(["full", "focused", "isolated"]);
+export class SessionScopeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "SessionScopeError";
+        this.code = code;
+    }
+}
+function comparisonKey(path, caseSensitive) {
+    return caseSensitive ? path : path.toLowerCase();
+}
+/** Drop duplicate and descendant roots already covered by a selected parent. */
+export function collapseNestedRoots(roots, caseSensitive = process.platform !== "win32") {
+    const unique = new Map();
+    for (const root of roots) {
+        if (typeof root !== "string" || root.length === 0)
+            continue;
+        unique.set(comparisonKey(root, caseSensitive), root);
+    }
+    const candidates = [...unique.values()].sort((left, right) => left.length - right.length
+        || comparisonKey(left, caseSensitive).localeCompare(comparisonKey(right, caseSensitive)));
+    const result = [];
+    for (const candidate of candidates) {
+        if (result.some((root) => isLexicallyUnder(candidate, root, caseSensitive)))
+            continue;
+        result.push(candidate);
+    }
+    return result.sort((left, right) => comparisonKey(left, caseSensitive).localeCompare(comparisonKey(right, caseSensitive)));
+}
+/** Ancestors visible only for navigation from the workspace to content roots. */
+export function navigationRootsFor(workspaceRoot, roots, caseSensitive = process.platform !== "win32") {
+    if (!workspaceRoot)
+        return [];
+    const ancestors = new Map();
+    for (const root of roots) {
+        if (!isLexicallyUnder(root, workspaceRoot, caseSensitive))
+            continue;
+        let current = dirname(root);
+        while (isLexicallyUnder(current, workspaceRoot, caseSensitive)) {
+            ancestors.set(comparisonKey(current, caseSensitive), current);
+            if (comparisonKey(current, caseSensitive) === comparisonKey(workspaceRoot, caseSensitive))
+                break;
+            const parent = dirname(current);
+            if (parent === current)
+                break;
+            current = parent;
+        }
+    }
+    const distanceFromWorkspace = (path) => {
+        let distance = 0;
+        let current = path;
+        while (comparisonKey(current, caseSensitive) !== comparisonKey(workspaceRoot, caseSensitive)) {
+            const parent = dirname(current);
+            if (parent === current)
+                return Number.MAX_SAFE_INTEGER;
+            distance += 1;
+            current = parent;
+        }
+        return distance;
+    };
+    return [...ancestors.values()].sort((left, right) => distanceFromWorkspace(left) - distanceFromWorkspace(right)
+        || comparisonKey(left, caseSensitive).localeCompare(comparisonKey(right, caseSensitive)));
+}
+/** Validate and canonicalize roots immediately before persisting a snapshot. */
+export function normalizeSessionScopeRoots(input, workspaceRoot, options = {}) {
+    const { allowExternalRoots = false, caseSensitive = process.platform !== "win32", paths = DEFAULT_PATH_SERVICES, } = options;
+    if (!Array.isArray(input)) {
+        throw new SessionScopeError(SESSION_SCOPE_ERROR.INVALID_ROOT, "Invalid session scope root list.");
+    }
+    if (input.length > MAX_ROOTS) {
+        throw new SessionScopeError(SESSION_SCOPE_ERROR.INVALID_ROOT, `Session scope supports at most ${MAX_ROOTS} roots.`);
+    }
+    if (!isAbsolute(workspaceRoot) || !paths.isDirectory(workspaceRoot)) {
+        throw new SessionScopeError(SESSION_SCOPE_ERROR.STALE_WORKSPACE, "The session workspace is unavailable.");
+    }
+    const lexicalWorkspace = resolve(workspaceRoot);
+    const canonicalWorkspace = paths.canonical(workspaceRoot);
+    const roots = [];
+    for (const candidate of input) {
+        if (typeof candidate !== "string" || !isAbsolute(candidate) || !paths.isDirectory(candidate)) {
+            throw new SessionScopeError(SESSION_SCOPE_ERROR.INVALID_ROOT, "A selected session scope root is invalid or unavailable.");
+        }
+        const lexicalCandidate = resolve(candidate);
+        const canonicalCandidate = paths.canonical(candidate);
+        const lexicalInside = isLexicallyUnder(lexicalCandidate, lexicalWorkspace, caseSensitive);
+        const canonicalInside = isLexicallyUnder(canonicalCandidate, canonicalWorkspace, caseSensitive);
+        if (!allowExternalRoots && !lexicalInside && !canonicalInside) {
+            throw new SessionScopeError(SESSION_SCOPE_ERROR.OUTSIDE_WORKSPACE, "A selected path is outside the session workspace.");
+        }
+        if (!allowExternalRoots && lexicalInside && !canonicalInside) {
+            throw new SessionScopeError(SESSION_SCOPE_ERROR.SYMLINK_ESCAPE, "A selected path resolves outside the session workspace.");
+        }
+        roots.push(canonicalCandidate);
+    }
+    return collapseNestedRoots(roots, caseSensitive);
+}
+function isScopeMode(value) {
+    return typeof value === "string" && MODES.has(value);
+}
+function latestScopeData(events) {
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        if (events[index]?.type === SESSION_SCOPE_EVENT)
+            return events[index]?.data;
+    }
+    return undefined;
+}
+function foldedRoots(roots, workspaceRoot, caseSensitive) {
+    if (!Array.isArray(roots) || !workspaceRoot)
+        return [];
+    const valid = roots.flatMap((root) => {
+        if (typeof root !== "string" || !isAbsolute(root))
+            return [];
+        const canonicalRoot = canonicalPath(root);
+        return isLexicallyUnder(canonicalRoot, workspaceRoot, caseSensitive)
+            ? [canonicalRoot]
+            : [];
+    });
+    return collapseNestedRoots(valid, caseSensitive);
+}
+/** Fold new durable state, falling back to the upstream event only for legacy sessions. */
+export function effectiveSessionScope(events, sessionHeader = {}, caseSensitive = process.platform !== "win32") {
+    const data = latestScopeData(events);
+    const headerRoot = typeof sessionHeader.cwd === "string" ? sessionHeader.cwd : "";
+    const canonicalHeaderRoot = headerRoot ? canonicalPath(headerRoot) : "";
+    if (data !== undefined) {
+        const validSnapshot = data.version === 1 && isScopeMode(data.mode);
+        const mode = validSnapshot ? data.mode : "focused";
+        const eventRoot = typeof data.workspaceRoot === "string" ? data.workspaceRoot : "";
+        const canonicalEventRoot = eventRoot ? canonicalPath(eventRoot) : "";
+        const workspaceRoot = canonicalHeaderRoot || canonicalEventRoot;
+        if (mode === "full")
+            return { mode, workspaceRoot, roots: [], navigationRoots: [] };
+        // Malformed or stale persisted restrictions fail closed instead of widening
+        // the session back to the full workspace.
+        const stale = Boolean(canonicalHeaderRoot
+            && canonicalEventRoot
+            && comparisonKey(canonicalHeaderRoot, caseSensitive) !== comparisonKey(canonicalEventRoot, caseSensitive));
+        const roots = validSnapshot && !stale
+            ? foldedRoots(data.roots, workspaceRoot, caseSensitive)
+            : [];
+        return {
+            mode,
+            workspaceRoot,
+            roots,
+            navigationRoots: navigationRootsFor(workspaceRoot, roots, caseSensitive),
+        };
+    }
+    if (events.some((event) => event.type === SELECTION_EVENT)) {
+        const legacy = selectionOf(events);
+        const workspaceRoot = canonicalHeaderRoot
+            || (legacy.workspaceRoot ? canonicalPath(legacy.workspaceRoot) : "");
+        const roots = foldedRoots(legacy.roots, workspaceRoot, caseSensitive);
+        return {
+            mode: "focused",
+            workspaceRoot,
+            roots,
+            navigationRoots: navigationRootsFor(workspaceRoot, roots, caseSensitive),
+        };
+    }
+    return { mode: "full", workspaceRoot: canonicalHeaderRoot, roots: [], navigationRoots: [] };
+}
+export function createSessionScopeEvent(mode, roots, workspaceRoot, source, options) {
+    const canonicalWorkspaceRoot = (options?.paths ?? DEFAULT_PATH_SERVICES).canonical(workspaceRoot);
+    return {
+        version: 1,
+        mode,
+        workspaceRoot: canonicalWorkspaceRoot,
+        roots: mode === "full" ? [] : normalizeSessionScopeRoots(roots, workspaceRoot, options),
+        source,
+    };
+}
+//# sourceMappingURL=session-scope.js.map

package/lib/session-scope.js.map

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

package/lib/tool-guard.d.ts

@@ -0,0 +1,52 @@
+import type { ScopeSession } from "./host-api.js";
+import { type ScopedFilesystemOperation } from "./scope-visibility.js";
+export interface ScopeToolExecution {
+    callId?: string;
+    rootCallId?: string;
+    token?: symbol;
+    parent?: symbol;
+    name: string;
+    arguments: unknown;
+    agent?: {
+        session?: ScopeSession;
+    };
+    signal?: AbortSignal;
+}
+export interface ScopeToolExecutionResult {
+    isError: boolean;
+    value?: unknown;
+    content: unknown[];
+    error?: unknown;
+    additionalContexts?: unknown[];
+}
+export interface ScopeToolDispatcher {
+    execute(execution: ScopeToolExecution): Promise<ScopeToolExecutionResult>;
+}
+export interface ScopeToolGuardOptions {
+    splitBroadSearches?: boolean;
+    isolatedBackendReady?: boolean;
+    sandboxMode?: string;
+}
+export interface ToolPathRequest {
+    path: string;
+    operation: ScopedFilesystemOperation;
+}
+export interface ScopeToolAdapter {
+    name: string;
+    extractPaths(argumentsValue: unknown): ToolPathRequest[];
+}
+export declare const DEFAULT_TOOL_ADAPTERS: readonly ScopeToolAdapter[];
+export declare class ScopeToolAdapterRegistry {
+    private readonly adapters;
+    constructor(adapters?: readonly ScopeToolAdapter[]);
+    register(adapter: ScopeToolAdapter): () => void;
+    requests(execution: ScopeToolExecution): ToolPathRequest[];
+}
+/** Monotonic tool guard: undefined allows; a stable reason string denies. */
+export declare function guardScopeToolExecution(execution: ScopeToolExecution, adapters: ScopeToolAdapterRegistry, fallbackWorkspaceRoot?: string, options?: ScopeToolGuardOptions): string | undefined;
+/**
+ * Split a navigation-root glob/grep into child calls under content roots.
+ * Direct searches already inside one content root pass through unchanged.
+ */
+export declare function dispatchScopedSearchExecution(execution: ScopeToolExecution, dispatcher: ScopeToolDispatcher, next: () => Promise<ScopeToolExecutionResult>, fallbackWorkspaceRoot?: string): Promise<ScopeToolExecutionResult>;
+//# sourceMappingURL=tool-guard.d.ts.map

package/lib/tool-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-guard.d.ts","sourceRoot":"","sources":["../src/tool-guard.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,uBAAuB,CAAC;AAO/B,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,YAAY,CAAA;KAAE,CAAC;IACnC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,kBAAkB,CAAC,EAAE,OAAO,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,SAAS,EAAE,kBAAkB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;CAC3E;AAED,MAAM,WAAW,qBAAqB;IACpC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,yBAAyB,CAAC;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,cAAc,EAAE,OAAO,GAAG,eAAe,EAAE,CAAC;CAC1D;AA6CD,eAAO,MAAM,qBAAqB,EAAE,SAAS,gBAAgB,EAQ3D,CAAC;AAEH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;IAEhE,YAAY,QAAQ,GAAE,SAAS,gBAAgB,EAA0B,EAExE;IAED,QAAQ,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,IAAI,CAQ9C;IAED,QAAQ,CAAC,SAAS,EAAE,kBAAkB,GAAG,eAAe,EAAE,CAEzD;CACF;AA+BD,6EAA6E;AAC7E,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,kBAAkB,EAC7B,QAAQ,EAAE,wBAAwB,EAClC,qBAAqB,SAAK,EAC1B,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAwCpB;AA4DD;;;GAGG;AACH,wBAAsB,6BAA6B,CACjD,SAAS,EAAE,kBAAkB,EAC7B,UAAU,EAAE,mBAAmB,EAC/B,IAAI,EAAE,MAAM,OAAO,CAAC,wBAAwB,CAAC,EAC7C,qBAAqB,SAAK,GACzB,OAAO,CAAC,wBAAwB,CAAC,CA+BnC"}