llm4s-docs
API
Generated with
llm4s-docs/org.llm4s/org.llm4s.agent/org.llm4s.agent.harness/FileBackend

FileBackend

org.llm4s.agent.harness.FileBackend
See theFileBackend companion object
@Experimental
trait FileBackend

Where an agent's files live: thread state (StateFileBackend), a LongTermStore (StoreFileBackend), several at once (CompositeBackend), or one chosen per run (FileBackend.resolved).

A backend owns the four obligations of every mutation, so the tools that call it need not know them:

  • '''Order.''' locks(path) are the LockKeys a mutation of path holds; a tool declares them with AgentToolSpec.withLocks, so mutations of one path in one batch apply in call order. Reads take no lock.
  • '''Replay.''' A mutation outside thread state runs through C4's replay guard of its target's class, under ctx.effectKey(operation, path). A state mutation is the StateUpdate it returns, which the runtime commits with the call; it needs no guard.
  • '''Bounds.''' Every result is bounded by limit and the backend's own limits, and every store by a limit the backend checks itself.
  • '''Tenant.''' A backend shared across threads is scoped by the run's tenant, or built per tenant by a resolver.

A refusal the model should see is a BackendRefused; any other Left is a failure the task must not hide (BackendRefused.toolOutcome).

Attributes

Companion
object
Graph
Supertypes
class Object
trait Matchable
class Any
Known subtypes

Members list

Value members

Abstract methods

def delete(path: VPath, ctx: FileContext): Result[(FileDeleted, StateUpdate)]

Deletes the file, or the empty directory, path.

Deletes the file, or the empty directory, path.

Attributes

def edit(path: VPath, old: String, replacement: String, replaceAll: Boolean, ctx: FileContext): Result[(FileEdited, StateUpdate)]

Replaces old with replacement in the file path: the one occurrence, or every occurrence when replaceAll. Refused when old is empty or absent, or occurs more than once and not replaceAll.

Replaces old with replacement in the file path: the one occurrence, or every occurrence when replaceAll. Refused when old is empty or absent, or occurs more than once and not replaceAll.

Attributes

def find(under: VPath, accept: VPath => Boolean, limit: Int, ctx: FileContext): Result[Listing[VPath]]

The files within under that accept takes, in path order, at most limit: accept is applied before the limit, so a file it refuses never takes a place (a composite passes a predicate that refuses the paths a mount shadows, and relies on this to fill its limit with visible files). search likewise.

The files within under that accept takes, in path order, at most limit: accept is applied before the limit, so a file it refuses never takes a place (a composite passes a predicate that refuses the paths a mount shadows, and relies on this to fill its limit with visible files). search likewise.

Attributes

def locks(path: VPath): Set[LockKey]

The locks a mutation of path holds.

The locks a mutation of path holds.

Attributes

def ls(path: VPath, limit: Int, ctx: FileContext): Result[Listing[FileInfo]]

The entries directly beneath the directory path, in path order, at most limit.

The entries directly beneath the directory path, in path order, at most limit.

Attributes

def read(path: VPath, offset: Int, limit: Int, ctx: FileContext): Result[FileLines]

At most limit lines of the file path, from the 0-based line offset.

At most limit lines of the file path, from the 0-based line offset.

Attributes

def search(under: VPath, regex: Pattern, accept: VPath => Boolean, limit: Int, ctx: FileContext): Result[Listing[GrepMatch]]

The lines matching regex of the files within under that accept takes, in path then line order. regex is the model's: match it with org.llm4s.security.RegexSafetyManager.safeFind, never a bare matcher, so a catastrophic pattern is bounded and cannot overflow the stack.

The lines matching regex of the files within under that accept takes, in path then line order. regex is the model's: match it with org.llm4s.security.RegexSafetyManager.safeFind, never a bare matcher, so a catastrophic pattern is bounded and cannot overflow the stack.

Attributes

def write(path: VPath, content: String, ctx: FileContext): Result[(FileWritten, StateUpdate)]

Writes the file path, creating it or replacing it.

Writes the file path, creating it or replacing it.

Attributes

def writes: Set[StateKey[_, _]]

The state keys the StateUpdates of this backend's mutations touch; a tool declares them in writes.

The state keys the StateUpdates of this backend's mutations touch; a tool declares them in writes.

Attributes

Concrete methods

final def glob(pattern: Glob, under: VPath, limit: Int, ctx: FileContext): Result[Listing[VPath]]

The files within under whose path relative to under matches pattern.

The files within under whose path relative to under matches pattern.

Attributes

final def grep(regex: String, under: VPath, include: Option[Glob], limit: Int, ctx: FileContext): Result[Listing[GrepMatch]]

The lines matching regex in the files within under. include filters the files: a pattern with no / matches a file's name, one with a / its path relative to under (as ripgrep's --glob).

The lines matching regex in the files within under. include filters the files: a pattern with no / matches a file's name, one with a / its path relative to under (as ripgrep's --glob).

Attributes

Generated with