Class PathHelper

Namespace

Oscova.Agents.Utils

Assembly

Oscova.Agents.dll

Path security utilities for containment checks and safe logging.

public static class PathHelper

Inheritance

object

PathHelper

Inherited Members

object.Equals(object?)

object.Equals(object?, object?)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object?, object?)

object.ToString()

Methods

ArePathsEqual(string, string)

Returns true when two paths resolve to the same filesystem location. Uses the platform's default path comparison rules.

GetRelativePathUnderRoot(string, string, StringComparison)

Returns a path relative to a named root, or null when it lies outside that root.

HasSymlinkInPath(string, string)

Returns true if any path segment beneath normalizedDirectoryPath is a symlink or reparse point. Inaccessible segments are treated conservatively as unsafe.

IsDirectChildOfAnyDirectory(string, IEnumerable<string>)

Returns true when relativePath is a direct file child of any supplied top-level directory name.

IsPathWithinAnyDirectory(string, IReadOnlyList<string>)

Returns true if fullPath is located inside any of the supplied directory roots.

IsPathWithinDirectory(string, string)

Returns true if fullPath is located inside normalizedDirectoryPath. Uses System.IO.Path.GetRelativePath(System.String,System.String) which is natively case-sensitive on Linux/macOS and case-insensitive on Windows.

ResolveAuthorizedHostPath(string, IReadOnlyList<AllowedDirectory>, WorkspacePathAccess)

Resolves and authorizes an agent path against current directory grants, including symlink and access checks.

ResolveToAgentPath(string, IReadOnlyList<AllowedDirectory>)

Converts a resolved host path to the active run's agent-facing path or throws a tool-friendly error.

ResolveToHostPath(string, Func<IReadOnlyList<AllowedDirectory>>)

Resolves an agent-supplied path through a live allowed-directory resolver or throws a tool-friendly error.

ResolveWorkingDirectoryAgentPath(IReadOnlyList<AllowedDirectory>)

Returns the agent-facing path of the working directory (e.g. /workspace/default or a named workspace in sandbox mode). Use this wherever the shell or system prompt must advertise a working directory — it matches what the shell is actually mounted at.

ResolveWorkingDirectoryHostPath(IReadOnlyList<AllowedDirectory>)

Returns the host directory that acts as the working directory for relative agent paths.

SanitizeForLog(string)

Replaces control characters in a file path with '?' to prevent log injection via crafted filenames containing newlines or other control characters.

SanitizeMountName(string)

Converts arbitrary workspace labels into stable container mount names.

ToExtraMountAgentPath(string)

Builds the agent-facing mount path for an extra (non-workspace, non-data) allowed directory, e.g. /mnt/chat-attachments-for-this-thread. Single owner of the /mnt/<label> rule.

ToPlatformRelativePath(string)

Converts a slash-separated relative path into the current platform's directory-separator form.

ToSlashSeparatedRelativePath(string)

Converts a relative path to the forward-slash form used by skill files, zip entries, and model-facing paths.

ToWorkspaceAgentPath(string)

Builds the agent-facing mount path for a named workspace, e.g. /workspace/default. Single owner of the /workspace/<name> rule.

TryGetContainingDirectory(string, IReadOnlyList<AllowedDirectory>, out AllowedDirectory?)

Finds the most specific allowed directory that contains fullPath.

TryResolveToAgentPath(string, IReadOnlyList<AllowedDirectory>, out string)

Converts a resolved host path back to the most specific agent-facing allowed-directory path.

TryResolveToHostPath(string, IReadOnlyList<AllowedDirectory>, string?, out string)

THE PATH CONTRACT. Every filesystem-facing tool (read, write, list, PDF, and any future or plugin tool) resolves an agent-supplied path to a host path through this one method, then does its IO on the host. The agent is only ever shown agent-facing paths:

• sandbox mode: /workspace/<name>, /data, /mnt/<label>;
• host / disabled mode: the real host paths of the OS the app runs on.

In sandbox mode those agent-facing roots are bind-mounted into the container at exactly these paths, so a file tool (host IO) and the sandboxed shell see the same bytes. Relative paths resolve against the working directory in every mode. The argument is never mutated, so tool output keeps showing the agent the path it passed.

The invariant that keeps both surfaces consistent: never present the agent a path that does not resolve here / is not mounted into the sandbox. Any new tool must resolve through this method (or Oscova.Agents.Utils.PathHelper.ResolveToHostPath(System.String,System.Func{System.Collections.Generic.IReadOnlyList{Oscova.Agents.Workspace.AllowedDirectory}})) rather than calling System.IO on a raw argument.