@a3s-lab/code 2.6.0 → 3.1.0

package/README.md

@@ -55,9 +55,8 @@ Scripts can also be loaded from workspace-relative `.js` or `.mjs` files with
 ## 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:
+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')
@@ -74,6 +73,39 @@ 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
@@ -126,9 +158,54 @@ await session.tasks([
 ])
 ```
 
+For automatic subagent delegation, `autoParallel: false` disables automatic
+parallel fan-out while keeping manual `parallel_task` / `session.tasks(...)`
+available:
+
+```js
+const session = agent.session('/my-project', {
+  autoDelegation: { enabled: true, maxTasks: 4 },
+  maxParallelTasks: 8,
+  autoParallel: false,
+})
+```
+
 Use `session.toolNames()` for names and `session.toolDefinitions()` when a UI
 needs the full model-visible schemas.
 
+## Evidence And Artifacts
+
+Tool outputs that exceed the inline display budget are retained as session
+artifacts. Use `artifactStoreLimits` to tune retention and `getArtifact(...)`
+to retrieve retained content by URI:
+
+```js
+const session = agent.session('/my-project', {
+  artifactStoreLimits: { maxArtifacts: 64, maxBytes: 8 * 1024 * 1024 },
+})
+
+const artifact = session.getArtifact('a3s://tool-output/read/abc123')
+if (artifact) console.log(artifact.content)
+```
+
+External verification systems can attach their reports to the same session
+evidence stream:
+
+```js
+session.recordVerificationReports([{
+  schema: 'a3s.verification_report.v1',
+  subject: 'sdk:tests',
+  status: 'passed',
+  checks: [{
+    id: 'check:sdk',
+    kind: 'test',
+    description: 'Run SDK tests',
+    status: 'passed',
+    required: true,
+  }],
+}])
+```
+
 ## Object-Shaped Direct Tools
 
 New direct helpers use option objects when the command can grow over time:

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
@@ -80,6 +88,32 @@ export interface VerificationCommand {
   required?: boolean
   timeoutMs?: number
 }
+export type VerificationStatus = 'passed' | 'failed' | 'needs_review' | 'skipped'
+export interface VerificationCheck {
+  id: string
+  kind: string
+  description: string
+  status: VerificationStatus
+  required?: boolean
+  suggested_tools?: Array<string>
+  evidence_uris?: Array<string>
+  residual_risk?: string
+}
+export interface VerificationReport {
+  schema: string
+  subject: string
+  status: VerificationStatus
+  checks: Array<VerificationCheck>
+  residual_risks?: Array<string>
+}
+export interface ToolArtifact {
+  artifact_id: string
+  artifact_uri: string
+  tool_name: string
+  content: string
+  original_bytes: number
+  shown_bytes: number
+}
 export interface ToolResult {
   name: string
   output: string
@@ -88,7 +122,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
@@ -166,6 +225,16 @@ export interface InlineSkill {
   /** Markdown content for the skill. */
   content: string
 }
+export interface AutoDelegationOptions {
+  /** Enable runtime-driven automatic child-agent delegation. */
+  enabled?: boolean
+  /** Allow automatic delegation to launch multiple child agents in parallel. */
+  autoParallel?: boolean
+  /** Minimum local confidence required to auto-delegate a child task. */
+  minConfidence?: number
+  /** Maximum number of automatic child tasks per user request. */
+  maxTasks?: number
+}
 export interface JsMemoryStore {
   backend: string
   dir?: string
@@ -212,6 +281,79 @@ export interface JsS3BackendConfig {
   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.
@@ -302,6 +444,13 @@ export interface PendingConfirmation {
   /** Milliseconds remaining before the confirmation times out. */
   remainingMs: number
 }
+/** Retention limits for large tool/program artifacts. */
+export interface ArtifactStoreLimits {
+  /** Maximum number of artifacts retained by a session. */
+  maxArtifacts?: number
+  /** Maximum total artifact content bytes retained by a session. */
+  maxBytes?: number
+}
 export interface SessionOptions {
   /** Override the default model. Format: "provider/model" (e.g., "openai/gpt-4o"). */
   model?: string
@@ -342,6 +491,8 @@ export interface SessionOptions {
   autoCompact?: boolean
   /** Context usage threshold (0.0–1.0) to trigger auto-compaction (default: 0.8). */
   autoCompactThreshold?: number
+  /** Retention limits for large tool/program artifacts. */
+  artifactStoreLimits?: ArtifactStoreLimits
   /**
    * Long-term memory store backend.
    *
@@ -386,6 +537,23 @@ export interface SessionOptions {
    * ```
    */
   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."
@@ -407,6 +575,16 @@ export interface SessionOptions {
   inlineSkills?: Array<InlineSkill>
   /** Override maximum number of tool-call rounds for this session. */
   maxToolRounds?: number
+  /** Override maximum sibling parallel branches for this session. */
+  maxParallelTasks?: number
+  /** Override automatic child-agent delegation for this session. */
+  autoDelegation?: AutoDelegationOptions
+  /**
+   * Global session-level kill switch for automatic parallel child-agent fan-out.
+   *
+   * Manual `parallel_task` calls remain available when this is false.
+   */
+  autoParallel?: boolean
   /**
    * Sampling temperature (0.0–1.0). Overrides the provider default.
    * Only applied when `model` is also set.
@@ -1083,7 +1261,9 @@ export declare class Session {
   /** Return compact execution trace events recorded for this session. */
   traceEvents(): any
   /** Return structured verification reports recorded for this session. */
-  verificationReports(): any
+  verificationReports(): Array<VerificationReport>
+  /** Add externally produced verification reports to this session. */
+  recordVerificationReports(reports: Array<VerificationReport> | VerificationReport): void
   /** Return a structured verification summary for this session. */
   verificationSummary(): any
   /** Return a concise human-readable verification summary for this session. */
@@ -1188,6 +1368,8 @@ export declare class Session {
   toolNames(): Array<string>
   /** Return full model-visible tool definitions currently registered on this session. */
   toolDefinitions(): any
+  /** Return a stored tool artifact by URI, or null if it is not retained. */
+  getArtifact(artifactUri: string): ToolArtifact | null
   /**
    * Register a hook for lifecycle event interception.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a3s-lab/code",
-  "version": "2.6.0",
+  "version": "3.1.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.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"
+    "@a3s-lab/code-darwin-arm64": "3.1.0",
+    "@a3s-lab/code-linux-x64-gnu": "3.1.0",
+    "@a3s-lab/code-linux-x64-musl": "3.1.0",
+    "@a3s-lab/code-linux-arm64-gnu": "3.1.0",
+    "@a3s-lab/code-linux-arm64-musl": "3.1.0",
+    "@a3s-lab/code-win32-x64-msvc": "3.1.0"
   }
 }