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.
Path canonicalization contract. Every method that takes a path
argument MUST canonicalize the input via Canonicalize(string)
(file paths) or CanonicalizeDirectory(string) (directory paths,
e.g. the argument to ListDirectory(string, int)) before keying or comparing.
Implementations MUST also use PathComparer (or a comparer
with equivalent semantics) for path equality. This guarantees that strings like
kb/foo.md, ./kb/foo.md, kb//foo.md, kb/./foo.md,
/kb/foo.md, and kb/foo.md/ all refer to the same logical file. See
WorkspacePath for the full canonicalization rules and the rejection
list (notably: .. segments are not permitted).
The ActualPath values returned in ReadFileResult and
WriteFileResult are the canonical form. Callers can rely on the
returned path being safe to feed back into other workspace methods.
Exceptions vs <see cref="T:NexusLabs.Needlr.AgentFramework.Workspace.WorkspaceResult1"/>.</strong> Invalid path
arguments (null, empty, whitespace-only, containing..`, canonicalizing to
empty for file APIs) throw System.ArgumentNullException or
System.ArgumentException directly — they are NOT wrapped in
Fail(Exception). Fail(Exception) is
reserved for valid paths where the workspace operation legitimately fails (file
missing, compare-exchange content mismatch, etc.).
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>