@a3s-lab/code 2.5.0 → 3.0.0

package/README.md

@@ -52,6 +52,60 @@ 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 an explicit typed backend through the same
+option surface used by remote, browser, DFS, and container-backed workspaces:
+
+```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')
+```
+
+### S3-compatible object storage
+
+`S3WorkspaceBackend` lets built-in file tools (`read`, `write`, `edit`,
+`patch`, `ls`) target any S3-compatible endpoint — AWS S3, MinIO, RustFS,
+Cloudflare R2, Backblaze B2, etc. `bash`, `git`, `grep`, and `glob` are
+automatically hidden from the model because object storage cannot service
+them.
+
+```js
+const { Agent, S3WorkspaceBackend } = require('@a3s-lab/code')
+
+const agent = await Agent.create('agent.acl')
+const session = agent.session('s3://workspace/users/u1/sessions/s1', {
+  workspaceBackend: new S3WorkspaceBackend({
+    endpoint: 'https://minio.local:9000',     // omit for AWS S3
+    region: 'us-east-1',
+    accessKeyId: 'AKIA...',
+    secretAccessKey: '...',
+    bucket: 'workspace',
+    prefix: 'users/u1/sessions/s1',
+    forcePathStyle: true,                     // true for MinIO/RustFS/R2
+  }),
+})
+
+await session.writeFile('notes/hello.txt', 'one\ntwo\n')
+await session.readFile('notes/hello.txt')
+await session.ls('notes')
+```
+
+S3 has no atomic read-modify-write, so concurrent writers to the same key
+overwrite each other (last-writer-wins). Partition workspaces per session or
+user via the `prefix` field when running multi-tenant.
+
 ## Planning Events
 
 Planning is automatic by default. Prefer the explicit tri-state

package/index.d.ts

@@ -71,6 +71,14 @@ export interface AgentEvent {
   verificationSummaryText?: string
   /** Extra data for events that don't map to standard fields (JSON-encoded) */
   data?: string
+  /**
+   * Structured discriminant for tool failures on `tool_end` events
+   * (JSON-encoded with a `type` field on the top level, e.g.
+   * `{"type":"version_conflict","path":"doc.md","expected":"etag-1","actual":"etag-2"}`).
+   * Undefined on success or untyped failure. Streaming consumers parse
+   * this to branch on the failure kind without scanning `toolOutput`.
+   */
+  errorKindJson?: string
 }
 export interface VerificationCommand {
   id: string
@@ -88,7 +96,32 @@ export interface ToolResult {
   metadataJson?: string
   /** Convenience JSON view of `metadata.document_runtime` when present. */
   documentRuntimeJson?: string
+  /**
+   * Structured discriminant for tool failures, JSON-encoded with a
+   * `type` field on the top level — e.g.
+   * `{"type":"version_conflict","path":"doc.md","expected":"etag-1","actual":"etag-2"}`.
+   * Undefined on success or untyped failure. SDK callers parse it to
+   * branch on the failure kind without scanning the `output` string.
+   */
+  errorKindJson?: string
 }
+
+/**
+ * Parsed shape of `ToolResult.errorKindJson` / `AgentEvent.errorKindJson`.
+ *
+ * Use a discriminated union on the `type` field; new variants may be
+ * added in future minor releases — callers should match exhaustively on
+ * the kinds they care about and fall through to a default branch for
+ * unknown ones.
+ */
+export type ToolErrorKind =
+  | { type: 'version_conflict'; path: string; expected: string; actual: string | null }
+  | { type: 'remote_git_conflict'; code: string; message: string }
+  | { type: 'not_found'; path: string }
+  | { type: 'invalid_argument'; message: string }
+  | { type: 'unsupported'; message: string }
+  | { type: 'timeout'; op: string; duration_ms: number }
+
 /** Execution limits for `Session.program`. */
 export interface ProgramScriptLimits {
   timeoutMs?: number
@@ -177,6 +210,115 @@ 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
+  /**
+   * Maximum bytes a single `read` may return. The backend rejects any
+   * response with `Content-Length` greater than this without buffering
+   * the body. Defaults to 10 MiB on the Rust side when omitted.
+   */
+  maxReadBytes?: number
+  /**
+   * Enable degraded `grep` / `glob` against this S3 backend. Off by
+   * default — object storage has no native search, so the only viable
+   * strategy is `LIST` + `GET` + regex, which can be slow and expensive.
+   */
+  searchEnabled?: boolean
+  /**
+   * Upper bound on objects considered per `grep` / `glob` call. Defaults
+   * to 500 on the Rust side. Ignored when `searchEnabled` is `false`.
+   */
+  maxObjectsScanned?: number
+  /**
+   * Per-object body-size ceiling for `grep` downloads. Larger objects are
+   * skipped (debug-traced). Defaults to 1 MiB on the Rust side. Ignored
+   * when `searchEnabled` is `false`.
+   */
+  maxGrepBytesPerObject?: number
+  /**
+   * Concurrent object downloads during `grep`. Defaults to 8 on the Rust
+   * side. Set lower when the gitserver / S3 endpoint rate-limits
+   * aggressively; set higher when latency dominates. Ignored when
+   * `searchEnabled` is `false`.
+   */
+  searchConcurrency?: number
+}
+/**
+ * Configuration for a `RemoteGitBackend` — an HTTP/JSON client that
+ * brings the `git` tool to non-local workspaces (S3, future container /
+ * DFS).
+ *
+ * Pass alongside `workspaceBackend` on a session to attach remote git
+ * on top of any filesystem backend.
+ */
+export interface JsRemoteGitBackendConfig {
+  /**
+   * Base URL of the gitserver, no trailing slash. The client builds
+   * `{baseUrl}/v1/repos/{repoId}/git/{op}` per the RFC.
+   */
+  baseUrl: string
+  /**
+   * Opaque repository identifier, URL-safe. Negotiated out of band
+   * with the gitserver operator.
+   */
+  repoId: string
+  /**
+   * Bearer token sent as `Authorization: Bearer <token>`. Required in
+   * production; omitting it emits a server-side warning and is only safe
+   * on a trusted localhost gitserver.
+   */
+  bearerToken?: string
+  /**
+   * mTLS client certificate path (PEM). When set together with `clientKeyPem`,
+   * the backend reads both files at construction and configures mTLS on the
+   * HTTP client. Setting only one of the pair errors at construction.
+   */
+  clientCertPem?: string
+  /**
+   * mTLS client private key path (PEM). PKCS#8 format expected for the
+   * `rustls-tls` backend. See `clientCertPem`.
+   */
+  clientKeyPem?: string
+  /** Per-call HTTP timeout in milliseconds. Defaults to 30 000. */
+  requestTimeoutMs?: number
+  /** Client-side cap on `diff` response bytes. Defaults to 1 MiB. */
+  maxDiffBytes?: number
+  /** Client-side cap on `log` `max_count`. Defaults to 200. */
+  maxLogEntries?: number
+}
 /**
  * Union type for AHP transport configuration.
  * Accepts any of: StdioTransport, HttpTransport, WebSocketTransport, UnixSocketTransport.
@@ -339,6 +481,34 @@ 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
+  /**
+   * Optional remote git provider. When set, the resulting session attaches
+   * a `RemoteGitBackend` on top of `workspaceBackend` so the built-in
+   * `git` tool is available even on object-storage workspaces.
+   *
+   * ```js
+   * agent.session('s3://workspace/u1/s1', {
+   *   workspaceBackend: new S3WorkspaceBackend({ ... }),
+   *   remoteGit: {
+   *     baseUrl: 'https://gitserver.internal',
+   *     repoId:  'u1/s1',
+   *     bearerToken: token,
+   *   },
+   * });
+   * ```
+   */
+  remoteGit?: JsRemoteGitBackendConfig
   /**
    * Custom role/identity prepended before the core agentic prompt.
    * Example: "You are a senior Python developer specializing in FastAPI."
@@ -698,6 +868,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 +1135,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": "3.0.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": "3.0.0",
+    "@a3s-lab/code-linux-x64-gnu": "3.0.0",
+    "@a3s-lab/code-linux-x64-musl": "3.0.0",
+    "@a3s-lab/code-linux-arm64-gnu": "3.0.0",
+    "@a3s-lab/code-linux-arm64-musl": "3.0.0",
+    "@a3s-lab/code-win32-x64-msvc": "3.0.0"
   }
 }