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.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.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>
Remarks¶
Callers that enumerate lines (e.g., MemoryExtensions.EnumerateLines()) benefit
from the zero-copy path. Callers that need a System.String should use
TryReadFile(string) instead.
IWorkspace.TryCompareExchange(string, string, string) Method¶
Atomically replaces file content only if the current content matches expectedContent. Returns a structured result indicating whether the exchange succeeded and why it failed if it didn't.
NexusLabs.Needlr.AgentFramework.Workspace.WorkspaceResult<NexusLabs.Needlr.AgentFramework.Workspace.CompareExchangeResult> TryCompareExchange(string path, string expectedContent, string newContent);
Parameters¶
path System.String
expectedContent System.String
newContent System.String
Returns¶
NexusLabs.Needlr.AgentFramework.Workspace.WorkspaceResult<CompareExchangeResult>
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.TryReadFile(string) Method¶
Reads the entire content of a file.
NexusLabs.Needlr.AgentFramework.Workspace.WorkspaceResult<NexusLabs.Needlr.AgentFramework.Workspace.ReadFileResult> TryReadFile(string path);
Parameters¶
path System.String
Returns¶
NexusLabs.Needlr.AgentFramework.Workspace.WorkspaceResult<ReadFileResult>
IWorkspace.TryWriteFile(string, string) Method¶
Writes content to a file, creating or overwriting it.
NexusLabs.Needlr.AgentFramework.Workspace.WorkspaceResult<NexusLabs.Needlr.AgentFramework.Workspace.WriteFileResult> TryWriteFile(string path, string content);
Parameters¶
path System.String
content System.String
Returns¶
NexusLabs.Needlr.AgentFramework.Workspace.WorkspaceResult<WriteFileResult>