IWorkspace
NexusLabs.Needlr.AgentFramework¶
NexusLabs.Needlr.AgentFramework.Workspace¶
IWorkspace Interface¶
Abstraction for file storage used by agent tools. Implementations may back onto an in-memory dictionary, a real file system, or a cloud blob store.
Derived
↳ InMemoryWorkspace
Remarks¶
IWorkspace is intentionally NOT auto-registered in DI. Consumers create workspace instances per-orchestration and attach them wherever they choose (execution context properties, direct injection, etc.). Needlr provides implementations as opt-in building blocks — never forced.
All paths use forward-slash separators and are normalized by implementations.
Methods¶
IWorkspace.CompareExchange(string, string, string) Method¶
Atomically replaces file content only if the current content matches expectedContent. Returns true if the swap succeeded, false if the content had changed.
Parameters¶
path System.String
expectedContent System.String
newContent System.String
Returns¶
Remarks¶
Enables optimistic concurrency for multi-agent pipelines where multiple agents may edit the same file. Callers read, transform, then CAS — if another agent wrote in between, the CAS fails and the caller can re-read and retry.
IWorkspace.FileExists(string) Method¶
Returns whether a file exists at the given path.
Parameters¶
path System.String
Returns¶
IWorkspace.GetFilePaths() Method¶
Returns all file paths in the workspace.
Returns¶
System.Collections.Generic.IEnumerable<System.String>
IWorkspace.ListDirectory(string, int) Method¶
Produces a tree-formatted directory listing starting at directory, descending up to maxDepth levels. The output format is implementation-defined but should be human-readable (tree characters, indentation, file/directory markers).
Parameters¶
directory System.String
The root directory to list. Use "" or "." for the workspace root.
maxDepth System.Int32
Maximum directory depth to descend. Defaults to 2.
Returns¶
System.String
A formatted string representing the directory tree.
IWorkspace.ReadFile(string) Method¶
Reads the entire content of a file.
Parameters¶
path System.String
Returns¶
Exceptions¶
System.IO.FileNotFoundException
The file does not exist.
IWorkspace.ReadFileAsMemory(string) Method¶
Reads the content of a file as a System.ReadOnlyMemory<> of System.Char. Implementations that store content as strings can return a zero-copy slice over the internal string via System.MemoryExtensions, avoiding per-read allocation.
Parameters¶
path System.String
Returns¶
System.ReadOnlyMemory<System.Char>
Exceptions¶
System.IO.FileNotFoundException
The file does not exist.
Remarks¶
Callers that enumerate lines (e.g., MemoryExtensions.EnumerateLines()) benefit
from the zero-copy path. Callers that need a System.String should use
ReadFile(string) instead.
IWorkspace.WriteFile(string, string) Method¶
Writes content to a file, creating or overwriting it.
Parameters¶
path System.String
content System.String