Theia API Documentation v1.77.0
    Preparing search index...
    Index
    accessibleRootContributions:
        | ContributionProvider<AccessibleRootContribution>
        | undefined
    aiConfiguration: AiConfigurationService
    envVariablesServer: EnvVariablesServer
    fileService: FileService
    GITIGNORE_FILE_NAME: ".gitignore" = '.gitignore'
    logger: ILogger
    preferences: PreferenceService
    workspaceService: WorkspaceService
    • get pathCaseSensitive(): boolean

      Whether path comparisons should be case-sensitive on the current backend. Windows and macOS default to case-insensitive file systems (NTFS, HFS+, APFS); Linux is treated as case-sensitive. This is a heuristic — a case-sensitive APFS volume on macOS or a case-insensitive volume mounted on Linux will be misclassified, but querying the actual file system would require a backend round-trip.

      Returns boolean

    • Asserts the target URI is reachable by the AI tools. Allowed when the URI is inside any workspace root, below a root contributed by an AccessibleRootContribution, or covered by an entry of the ai-features.workspaceFunctions.allowedExternalPaths preference. Workspace-scoped overrides of that preference are dropped when the workspace is not trusted.

      The target URI is normalized before the check so that literal .. segments and percent-encoded equivalents (e.g. %2e%2e) are resolved away — otherwise the path-prefix comparison would admit traversals.

      Note: symlinks within allow-listed directories are NOT canonicalized before the check. Only allow-list directories whose contents you trust.

      Parameters

      • targetUri: URI

      Returns Promise<void>

    • Resolves the configured external allow-list to URIs. Reads via the trust-aware AiConfigurationService so workspace-scoped overrides are dropped when the workspace is untrusted. Awaits the service's ready promise so that the trust state is resolved before the first preference read. Non-string entries, blanks, and entries that don't parse to a file:// URI are filtered out; URIs are returned in normalized form.

      Parameters

      • OptionalresourceUri: string

      Returns Promise<URI[]>

    • Returns the cached .gitignore matcher for the given root, reading the file at most once per root. A root with no (or unreadable) .gitignore is cached as undefined. The cache is invalidated by initializeGitignoreWatcher when the .gitignore is created, changed, or deleted, so individual exclusion checks need no filesystem RPC.

      Parameters

      • workspaceRoot: URI

      Returns Promise<Ignore | undefined>

    • Returns a mapping of root names to root URIs, in workspace order.

      Root names are assigned by WorkspaceService.getRootNames: the directory basename, or for roots sharing a basename, the shortest tail of the path that tells them apart (e.g. alice/app and bob/app). Every root thus has a name, and names are always the ending of the real path.

      Returns Map<string, URI>

    • Resolves a tool argument and asserts that it may be accessed. This is the single entry point every tool uses, so that a path is subjected to the same parsing and the same boundary check no matter which tool received it.

      Parameters

      • pathOrUri: string

      Returns Promise<URI>

      if the path cannot be resolved or points outside the accessible roots.

    • Resolves a relative path to a URI using a deterministic, synchronous algorithm. No filesystem I/O is performed — the agent is expected to use <rootName>/<relativePath> format. If the path cannot be resolved deterministically, an error is thrown.

      Resolution order:

      1. Root+relative: the path starts with a root name → resolve the rest relative to that root.
      2. Supra-relative: a root's basename appears as a segment, and any preceding material matches the preceding path components of the root → resolve the trailing portion. If this matches different files in several roots, the path is ambiguous.
      3. Single-root fallback: if exactly one workspace root, resolve relative to it.
      4. Error: tell the agent how to format the path.

      Parameters

      • relativePath: string

      Returns URI

    • If the given separator-normalized path is ~ or starts with ~/, expands the leading ~ against the user's home directory and returns the resulting URI. Returns undefined if the path does not start with ~ or the home directory cannot be resolved. The remainder is resolved in URI space to avoid Windows drive-letter round-tripping issues with URI.fromFilePath.

      Parameters

      • normalizedPath: string

      Returns Promise<URI | undefined>

    • Converts a user-supplied allow-list entry (absolute POSIX path, Windows drive path, ~-prefixed path, or file:// URI) into a normalized URI. Returns undefined for invalid input (relative paths, malformed URIs).

      Parameters

      • entry: string

      Returns Promise<URI | undefined>

    • Whether the already-separator-normalized path contains .. as a path segment (not merely as a substring of a filename like my..file.json).

      Parameters

      • normalizedPath: string

      Returns boolean

    • Whether an already-separator-normalized path is absolute on either platform: POSIX /foo, UNC //host/share, or Windows drive C:/foo.

      Parameters

      • normalized: string

      Returns boolean