@a3s-lab/code 3.0.0 → 3.2.0

package/README.md

@@ -158,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/extra-types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Hand-authored type declarations that complement the auto-generated
+ * `generated.d.ts`. These describe shapes that cross the SDK boundary as
+ * JSON (e.g. payloads inside `runs()`, `verificationReports()`,
+ * `errorKindJson` strings), not napi-bound objects.
+ *
+ * Keep field names matching the actual JSON wire format (snake_case where
+ * the Rust core serializes that way). Do not move these into Rust source —
+ * napi-derive would camelCase them and break consumers parsing the JSON.
+ */
+
+/**
+ * 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 }
+
+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
+}