@a3s-lab/code 2.5.0 → 2.6.0

package/README.md

@@ -52,6 +52,28 @@ Omit `allowedTools` to allow every registered session tool except `program`.
 Scripts can also be loaded from workspace-relative `.js` or `.mjs` files with
 `{ path: 'scripts/ptc/search.js' }`.
 
+## Workspace Backends And Direct Files
+
+The default workspace backend is the local filesystem rooted at the session
+workspace. SDK callers can pass the explicit typed backend now, using the same
+option surface that remote, browser, DFS, and container-backed workspaces will
+use:
+
+```js
+const { Agent, LocalWorkspaceBackend } = require('@a3s-lab/code')
+
+const agent = await Agent.create('agent.acl')
+const session = agent.session('/repo', {
+  workspaceBackend: new LocalWorkspaceBackend('/repo'),
+})
+
+await session.writeFile('notes.txt', 'one\ntwo\n')
+await session.readFile('notes.txt')
+await session.ls()
+await session.editFile('notes.txt', 'one', 'uno')
+await session.patchFile('notes.txt', '@@ -1,2 +1,2 @@\n uno\n-two\n+dos')
+```
+
 ## Planning Events
 
 Planning is automatic by default. Prefer the explicit tri-state

package/index.d.ts

@@ -177,6 +177,42 @@ export interface JsSessionStore {
 export interface JsSecurityProvider {
   kind: string
 }
+export interface JsWorkspaceBackend {
+  kind: string
+  root?: string
+  s3?: JsS3BackendConfig
+}
+/**
+ * Configuration for an S3-compatible workspace backend.
+ *
+ * Use this with [`S3WorkspaceBackend`] to point a session's built-in file
+ * tools at any S3-compatible endpoint (AWS S3, MinIO, RustFS, R2, etc.).
+ * `endpoint` is optional — omit it to use the AWS default. `prefix` is
+ * the logical workspace root inside the bucket; every workspace path
+ * becomes `<prefix>/<path>` when sent to S3.
+ */
+export interface JsS3BackendConfig {
+  /**
+   * Optional S3 endpoint URL. Omit for AWS S3 (the SDK will compute it
+   * from `region`). Set to `https://...` for MinIO / RustFS / R2 / etc.
+   */
+  endpoint?: string
+  /** AWS region. Defaults to `us-east-1` when omitted. */
+  region?: string
+  /** Static access key. Use `sessionToken` together when STS-issued. */
+  accessKeyId: string
+  secretAccessKey: string
+  sessionToken?: string
+  /** Bucket name. */
+  bucket: string
+  /**
+   * Logical workspace prefix inside the bucket (without leading/trailing
+   * slashes). Use `""` to make the bucket root the workspace.
+   */
+  prefix: string
+  /** `true` for MinIO / RustFS / most non-AWS endpoints; `false` for AWS S3. */
+  forcePathStyle?: boolean
+}
 /**
  * Union type for AHP transport configuration.
  * Accepts any of: StdioTransport, HttpTransport, WebSocketTransport, UnixSocketTransport.
@@ -339,6 +375,17 @@ export interface SessionOptions {
    * ```
    */
   securityProvider?: JsSecurityProvider
+  /**
+   * Workspace backend used by built-in tools.
+   *
+   * Pass `new LocalWorkspaceBackend("/repo")` to explicitly use the local
+   * filesystem backend. This option is the SDK surface for future remote,
+   * browser, DFS, and container-backed workspace implementations.
+   * ```js
+   * agent.session('/repo', { workspaceBackend: new LocalWorkspaceBackend('/repo') });
+   * ```
+   */
+  workspaceBackend?: JsWorkspaceBackend
   /**
    * Custom role/identity prepended before the core agentic prompt.
    * Example: "You are a senior Python developer specializing in FastAPI."
@@ -698,6 +745,52 @@ export declare class DefaultSecurityProvider {
   kind: string
   constructor()
 }
+/**
+ * Local filesystem workspace backend.
+ *
+ * This is the explicit typed form of the default local workspace behavior.
+ * It is useful when callers want to pass workspace backends through the same
+ * option surface that remote/browser backends will use.
+ *
+ * ```js
+ * agent.session('/repo', { workspaceBackend: new LocalWorkspaceBackend('/repo') });
+ * ```
+ */
+export declare class LocalWorkspaceBackend {
+  kind: string
+  root: string
+  /** Create a local filesystem workspace backend rooted at `root`. */
+  constructor(root: string)
+}
+/**
+ * S3-compatible object-storage workspace backend.
+ *
+ * Points built-in file tools (`read`, `write`, `edit`, `patch`, `ls`) at an
+ * S3-compatible bucket. Works with AWS S3, MinIO, RustFS, Cloudflare R2,
+ * Backblaze B2, and other S3-API-compatible services.
+ *
+ * `bash`, `git`, `grep`, and `glob` are intentionally **not** registered
+ * when this backend is in use — object storage cannot service them.
+ *
+ * ```js
+ * const backend = new S3WorkspaceBackend({
+ *   endpoint: 'https://minio.local:9000',
+ *   region: 'us-east-1',
+ *   accessKeyId: 'AKIA...',
+ *   secretAccessKey: '...',
+ *   bucket: 'workspace',
+ *   prefix: 'users/u1/sessions/s1',
+ *   forcePathStyle: true,
+ * });
+ * agent.session('s3://workspace/users/u1/sessions/s1', { workspaceBackend: backend });
+ * ```
+ */
+export declare class S3WorkspaceBackend {
+  kind: string
+  s3: JsS3BackendConfig
+  /** Create an S3-compatible workspace backend. */
+  constructor(config: JsS3BackendConfig)
+}
 /**
  * Stdio transport for AHP (Agent Harness Protocol).
  *
@@ -919,6 +1012,14 @@ export declare class Session {
   program(options: ProgramScriptOptions): Promise<ToolResult>
   /** Read a file from the workspace. */
   readFile(path: string): Promise<string>
+  /** Write a file in the workspace. */
+  writeFile(path: string, content: string): Promise<ToolResult>
+  /** List a directory in the workspace. */
+  ls(path?: string | undefined | null): Promise<ToolResult>
+  /** Edit a file by replacing text in the workspace. */
+  editFile(path: string, oldString: string, newString: string, replaceAll?: boolean | undefined | null): Promise<ToolResult>
+  /** Apply a unified diff patch to a workspace file. */
+  patchFile(path: string, diff: string): Promise<ToolResult>
   /** Execute a bash command in the workspace. */
   bash(command: string): Promise<string>
   /** Search for files matching a glob pattern. */

package/index.js

@@ -310,7 +310,7 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { formatVerificationSummary, EventStream, FileMemoryStore, FileSessionStore, MemorySessionStore, DefaultSecurityProvider, StdioTransport, HttpTransport, WebSocketTransport, UnixSocketTransport, Agent, Session, builtinSkills, BrowserBackend } = nativeBinding
+const { formatVerificationSummary, EventStream, FileMemoryStore, FileSessionStore, MemorySessionStore, DefaultSecurityProvider, LocalWorkspaceBackend, S3WorkspaceBackend, StdioTransport, HttpTransport, WebSocketTransport, UnixSocketTransport, Agent, Session, builtinSkills, BrowserBackend } = nativeBinding
 
 module.exports.formatVerificationSummary = formatVerificationSummary
 module.exports.EventStream = EventStream
@@ -318,6 +318,8 @@ module.exports.FileMemoryStore = FileMemoryStore
 module.exports.FileSessionStore = FileSessionStore
 module.exports.MemorySessionStore = MemorySessionStore
 module.exports.DefaultSecurityProvider = DefaultSecurityProvider
+module.exports.LocalWorkspaceBackend = LocalWorkspaceBackend
+module.exports.S3WorkspaceBackend = S3WorkspaceBackend
 module.exports.StdioTransport = StdioTransport
 module.exports.HttpTransport = HttpTransport
 module.exports.WebSocketTransport = WebSocketTransport

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a3s-lab/code",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "A3S Code - Native Node.js bindings for the coding-agent runtime",
   "main": "index.js",
   "types": "index.d.ts",
@@ -40,11 +40,11 @@
     "test:helpers": "node test-helpers.mjs"
   },
   "optionalDependencies": {
-    "@a3s-lab/code-darwin-arm64": "2.5.0",
-    "@a3s-lab/code-linux-x64-gnu": "2.5.0",
-    "@a3s-lab/code-linux-x64-musl": "2.5.0",
-    "@a3s-lab/code-linux-arm64-gnu": "2.5.0",
-    "@a3s-lab/code-linux-arm64-musl": "2.5.0",
-    "@a3s-lab/code-win32-x64-msvc": "2.5.0"
+    "@a3s-lab/code-darwin-arm64": "2.6.0",
+    "@a3s-lab/code-linux-x64-gnu": "2.6.0",
+    "@a3s-lab/code-linux-x64-musl": "2.6.0",
+    "@a3s-lab/code-linux-arm64-gnu": "2.6.0",
+    "@a3s-lab/code-linux-arm64-musl": "2.6.0",
+    "@a3s-lab/code-win32-x64-msvc": "2.6.0"
   }
 }