Skip to content

Commit 31b0d0a

Browse files
committed
docs(readme): refresh for v3.0 — typed errors + cloud workspace + Cargo dep
Three changes to README.md to align with the 3.0 release: * Add a "What's new in 3.0" subsection at the end of `## Why` so readers see the headline changes (cloud workspace, typed errors, conformance suite) without scrolling to the design-principles section. * Insert a "6b. Typed tool errors" example in both the Python and TypeScript "Main APIs At A Glance" tours, showing the dict / discriminated-union branch on `kind.type` that v3.0 introduced. Adds `type ToolErrorKind` to the TS import list. * Fix the stale Cargo dependency snippet: `a3s-code-core = { version = "2.6" }` -> `"3"`. Detailed "Typed Tool Errors (v3.0+)" deep-dive remains in the design principles section near the Remote Git Backend block.
1 parent 69eff96 commit 31b0d0a

1 file changed

Lines changed: 39 additions & 1 deletion

File tree

README.md

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,26 @@ Intent -> Context -> Action -> Observation -> Verification -> Compaction
3333

3434
Everything else is an extension of that loop.
3535

36+
### What's new in 3.0
37+
38+
- **Cloud-native workspace**`S3WorkspaceBackend` with ETag
39+
compare-and-swap for `edit`/`patch`, opt-in degraded `grep`/`glob`,
40+
and per-call cost metering via structured `tracing` events. Pair
41+
with `RemoteGitBackend` (HTTP/JSON, bearer or mTLS) to keep the
42+
`git` tool available on workspaces that have no `.git` directory.
43+
- **Typed tool errors end-to-end**`WorkspaceFileSystem` returns
44+
`WorkspaceResult<T>` over a `#[non_exhaustive] WorkspaceError`
45+
enum, and the discriminator surfaces at the SDK boundary as a
46+
`ToolErrorKind` (`errorKindJson` in Node, `error_kind` dict in
47+
Python). SDK callers branch on `.type` instead of regex-matching
48+
the output string.
49+
- **Backend conformance suite** — every workspace backend can be
50+
exercised against a shared set of invariants
51+
(`workspace::conformance`), validated against both
52+
`LocalWorkspaceBackend` and an `InMemoryFileSystem` reference impl.
53+
54+
Full migration notes are in [CHANGELOG.md](./CHANGELOG.md).
55+
3656
---
3757

3858
## Install
@@ -184,6 +204,14 @@ session.tool("generate_object", {
184204
"schema_name": "sentiment",
185205
})
186206

207+
# 6b. Typed tool errors (v3.0+) — branch on .type, not on output strings.
208+
result = session.tool("edit", {"file_path": "doc.md", "old_string": "...", "new_string": "..."})
209+
if kind := result.error_kind:
210+
if kind["type"] == "version_conflict":
211+
retry_after_reread(kind["path"], kind["expected"])
212+
elif kind["type"] == "not_found":
213+
create_file(kind["path"])
214+
187215
# 7. Runs and replay — typed runtime state, not text scraping.
188216
runs = session.runs()
189217
if runs:
@@ -251,6 +279,7 @@ import {
251279
HttpTransport,
252280
LocalWorkspaceBackend,
253281
S3WorkspaceBackend,
282+
type ToolErrorKind,
254283
} from '@a3s-lab/code';
255284

256285
// 1. Configure a session — typed extension options, not raw flags.
@@ -339,6 +368,15 @@ await session.tool('generate_object', {
339368
schema_name: 'sentiment',
340369
});
341370

371+
// 6b. Typed tool errors (v3.0+) — branch on .type, not on output strings.
372+
const edit = await session.tool('edit', { filePath: 'doc.md', oldString: '...', newString: '...' });
373+
if (edit.errorKindJson) {
374+
const kind: ToolErrorKind = JSON.parse(edit.errorKindJson);
375+
if (kind.type === 'version_conflict') retryAfterReread(kind.path, kind.expected);
376+
else if (kind.type === 'not_found') createFile(kind.path);
377+
else if (kind.type === 'remote_git_conflict') handleGitConflict(kind.code);
378+
}
379+
342380
// 7. Runs and replay — typed runtime state, not text scraping.
343381
const runs = await session.runs();
344382
const last = runs?.at(-1);
@@ -508,7 +546,7 @@ object storage cannot service them.
508546
```toml
509547
# Cargo.toml
510548
[dependencies]
511-
a3s-code-core = { version = "2.6", features = ["s3"] }
549+
a3s-code-core = { version = "3", features = ["s3"] }
512550
```
513551

514552
```rust

0 commit comments

Comments
 (0)