From 71e5cf9acc5de0dde9abb7d33833e726196250d1 Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Thu, 16 Jul 2026 15:35:35 +0200 Subject: [PATCH] release: 0.3.3 Co-authored-by: smolpaws Co-authored-by: openhands --- README.md | 2 +- docs/README.md | 3 ++- docs/RELEASE_0.3.3.md | 58 ++++++++++++++++++++++++++++++++++++++++++ docs/TRANSPILE_PLAN.md | 4 +-- package-lock.json | 4 +-- package.json | 2 +- 6 files changed, 66 insertions(+), 7 deletions(-) create mode 100644 docs/RELEASE_0.3.3.md diff --git a/README.md b/README.md index 57e3bdd..8719578 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Idiomatic TypeScript transpilation of the [OpenHands](https://github.com/OpenHan ## Status -`0.3.1` is the async persistence patch release of the fresh TypeScript transpilation. It covers the core SDK surfaces needed to build and run agent loops locally, adds durable local conversation history with non-blocking async FileStore locks for contended runtime paths, and documents the main architecture in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md): +`0.3.3` is the native OpenAI tool-completion parity release of the fresh TypeScript transpilation. It covers the core SDK surfaces needed to build and run agent loops locally, passes usable Agent tools through OpenAI Chat Completions and Responses, and documents the main architecture in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md): - zod-backed event, tool, settings, profile, and serialization models - profile-first LLM clients for OpenAI chat completions, OpenAI Responses, Anthropic, Gemini, and OpenAI-compatible profiles diff --git a/docs/README.md b/docs/README.md index e13a851..5b6eeb4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,7 +8,8 @@ This directory captures the working documentation for `@smolpaws/openhands-agent - [`TRANSPILE_PLAN.md`](TRANSPILE_PLAN.md) — upstream target, parity principles, accepted deviations, closed Agent tool-flow gap, and remaining roadmap. - [`REASONING_CAPABILITIES.md`](REASONING_CAPABILITIES.md) — provider/model-specific reasoning and thinking controls investigation plus proposed API shape. - [`PROMPT_CACHE_RETENTION.md`](PROMPT_CACHE_RETENTION.md) — GPT-5.6 prompt-cache retention evidence, live probes, and TypeScript SDK implementation decision. -- [`RELEASE_0.3.2.md`](RELEASE_0.3.2.md) — current 0.3.2 provider-native reasoning docs and GPT-5.6 prompt-cache retention release notes. +- [`RELEASE_0.3.3.md`](RELEASE_0.3.3.md) — current 0.3.3 native OpenAI tool-completion parity release notes. +- [`RELEASE_0.3.2.md`](RELEASE_0.3.2.md) — 0.3.2 provider-native reasoning docs and GPT-5.6 prompt-cache retention release notes. - [`RELEASE_0.3.1.md`](RELEASE_0.3.1.md) — 0.3.1 async persistence patch release notes. - [`RELEASE_0.3.0.md`](RELEASE_0.3.0.md) — 0.3.0 event-log persistence release notes. - [`RELEASE_0.2.0.md`](RELEASE_0.2.0.md) — 0.2.0 parity release notes. diff --git a/docs/RELEASE_0.3.3.md b/docs/RELEASE_0.3.3.md new file mode 100644 index 0000000..71ddb55 --- /dev/null +++ b/docs/RELEASE_0.3.3.md @@ -0,0 +1,58 @@ +# Release 0.3.3 + +`0.3.3` is the native OpenAI tool-completion parity release for `@smolpaws/openhands-agent`. It follows `0.3.2` by closing the Agent-to-LLM tool propagation gap against pinned Python `966340979be26c2162e9ab8805557b715e1f1a78` and documenting the provider-owned serialization boundary needed by the TypeScript agent-server port. + +## Highlights + +- Restored Agent-to-LLM tool propagation parity: + - `Agent.step()` now passes exactly the usable `ToolDefinition` instances to `LLMClient.complete()` + - the shared `LLMClient` interface remains a thin transport boundary with an optional `tools` argument + - non-usable tool definitions are not exposed to the model +- Added native OpenAI tool serialization: + - Chat Completions wraps `ToolDefinition` schemas in OpenAI's nested function-tool shape + - Responses uses the top-level function-tool shape + - empty tool lists omit the provider `tools` request field +- Preserved multi-tool execution behavior: + - returned tool calls still become ordered `ActionEvent`s + - `ParallelToolExecutor` continues to run pending batches without reintroducing confirmation gates +- Added executable evidence: + - red/green unit coverage for Agent tool propagation and OpenAI request serialization + - a live `native-openai-tools.ts` example proving real read/edit/read/finish dispatch with `gpt-5-nano` +- Updated architecture and transpilation docs to mark tool passing as required Python parity rather than an accepted deviation. + +## Verification + +Run before publishing/tagging: + +```sh +npm test +npm run typecheck +npm run lint +npm run build +npm run typecheck:examples +npm run test:examples +npm run typecheck:live +npm pack --dry-run +``` + +Verification result for the release commit: + +- `npm test` — passed, 39 files / 244 tests +- `npm run typecheck` — passed +- `npm run lint` — passed +- `npm run build` — passed +- `npm run typecheck:examples` — passed +- credential-free `npm run test:examples` — passed +- `npm run typecheck:live` — passed +- `npm pack --dry-run` — passed; tarball `smolpaws-openhands-agent-0.3.3.tgz`, package size 397.7 kB, unpacked size 1.9 MB, 72 files + +## Live evidence + +- `npm run live:openai-tools` against `gpt-5-nano` emitted native tool actions `read_file`, `edit_file`, `read_file`, and `finish`; tool executors ran and verified the README mutation. + +## Upgrade notes from 0.3.2 + +- Package metadata moves to `0.3.3`. +- Existing `LLMClient` implementations remain source-compatible because the new `tools` argument is optional. +- OpenAI Chat Completions and Responses clients now receive and serialize native tool definitions when an Agent has usable tools. +- Anthropic and Gemini native tool-calling are still intentionally separate follow-up provider phases. diff --git a/docs/TRANSPILE_PLAN.md b/docs/TRANSPILE_PLAN.md index 670f56a..380e151 100644 --- a/docs/TRANSPILE_PLAN.md +++ b/docs/TRANSPILE_PLAN.md @@ -10,9 +10,9 @@ OpenHands Python `agent-sdk` (local source: `~/repos/agent-sdk`, upstream `OpenHands/software-agent-sdk`). We transpile *anew* — we do **not** copy the outdated TS attempt in `oh-tab/packages/agent-sdk`. That older code is reference-only (tooling, tests). -## Current status after 0.3.1 +## Current status after 0.3.3 -The 0.3.1 line is the async persistence patch release. It covers the implemented core event/conversation/agent/tool/LLM/profile path, concrete tools, local/remote workspaces, hooks, critic, subagents, git helpers, MCP utilities, docs, examples, CI-style verification commands, durable local conversation history, and non-blocking async FileStore locks for contended runtime/server paths. +The 0.3.3 line is the native OpenAI tool-completion parity release. It covers the implemented core event/conversation/agent/tool/LLM/profile path, concrete tools, local/remote workspaces, hooks, critic, subagents, git helpers, MCP utilities, docs, examples, CI-style verification commands, durable local conversation history, non-blocking async FileStore locks for contended runtime/server paths, and Agent-to-LLM usable `ToolDefinition` propagation for OpenAI Chat Completions and Responses. The 0.2.0 parity line added compatibility/helper exports for smolpaws, profile-selected LLM field hygiene, Python-compatible message/content backward-compatibility shims, OpenAI tool-call serialization behavior, event merge guards, parallel-action guard coverage, and runnable examples for settings, conversation patterns, MCP, and remote workspace. diff --git a/package-lock.json b/package-lock.json index ae1e785..f413295 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@smolpaws/openhands-agent", - "version": "0.3.2", + "version": "0.3.3", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@smolpaws/openhands-agent", - "version": "0.3.2", + "version": "0.3.3", "license": "MIT", "dependencies": { "zod": "^4.4.3" diff --git a/package.json b/package.json index 05030e1..413ed22 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@smolpaws/openhands-agent", - "version": "0.3.2", + "version": "0.3.3", "description": "Idiomatic TypeScript transpilation of the OpenHands Python agent-sdk.", "license": "MIT", "type": "module",