Skip to content
Python

release: prepare SDK beta.2 and updated app-building skills (#857)

Rohit Prasadddb8b361bd58
diff --git a/.github/workflows/sdk-skills.yml b/.github/workflows/sdk-skills.yml
index 63270d63..6b5d68ee 100644
--- a/.github/workflows/sdk-skills.yml
+++ b/.github/workflows/sdk-skills.yml
@@ -23,3 +23,8 @@ jobs:
# No Rust build, Docker daemon, cloud credentials or model calls required.
- name: Test SDK compatibility and standalone skill installation
run: node --test skills/install.test.mjs skills/package.test.mjs harness/release/contract.test.mjs
+ - name: Compile skill examples against the SDK
+ run: |
+ npm --prefix harness/typescript-sdk ci
+ npm --prefix harness/typescript-sdk run build
+ node --test skills/snippets.test.mjs
diff --git a/harness/Cargo.lock b/harness/Cargo.lock
index 8c17913f..5a21cb04 100644
--- a/harness/Cargo.lock
+++ b/harness/Cargo.lock
@@ -1818,7 +1818,7 @@ dependencies = [
[[package]]
name = "openworker-artifacts"
-version = "0.1.0-beta.1"
+version = "0.1.0-beta.2"
dependencies = [
"anyhow",
"async-stream",
@@ -1843,7 +1843,7 @@ dependencies = [
[[package]]
name = "openworker-compliance"
-version = "0.1.0-beta.1"
+version = "0.1.0-beta.2"
dependencies = [
"anyhow",
"serde",
@@ -1869,7 +1869,7 @@ dependencies = [
[[package]]
name = "openworker-guardrails"
-version = "0.1.0-beta.1"
+version = "0.1.0-beta.2"
dependencies = [
"anyhow",
"futures-util",
@@ -1900,7 +1900,7 @@ dependencies = [
[[package]]
name = "openworker-runtime"
-version = "0.1.0-beta.1"
+version = "0.1.0-beta.2"
dependencies = [
"anyhow",
"base64 0.22.1",
@@ -1936,7 +1936,7 @@ dependencies = [
[[package]]
name = "openworker-sdk"
-version = "0.1.0-beta.1"
+version = "0.1.0-beta.2"
dependencies = [
"anyhow",
"async-stream",
@@ -1960,7 +1960,7 @@ dependencies = [
[[package]]
name = "openworker-security-adapters"
-version = "0.1.0-beta.1"
+version = "0.1.0-beta.2"
dependencies = [
"anyhow",
"openworker-guardrails",
@@ -2026,7 +2026,7 @@ dependencies = [
[[package]]
name = "openworker-store-postgres"
-version = "0.1.0-beta.1"
+version = "0.1.0-beta.2"
dependencies = [
"anyhow",
"native-tls",
@@ -2047,7 +2047,7 @@ dependencies = [
[[package]]
name = "openworker-telemetry"
-version = "0.1.0-beta.1"
+version = "0.1.0-beta.2"
dependencies = [
"anyhow",
"async-trait",
@@ -2070,7 +2070,7 @@ dependencies = [
[[package]]
name = "openworker-tools"
-version = "0.1.0-beta.1"
+version = "0.1.0-beta.2"
dependencies = [
"anyhow",
"serde",
diff --git a/harness/Cargo.toml b/harness/Cargo.toml
index fd288c4f..6de2ff71 100644
--- a/harness/Cargo.toml
+++ b/harness/Cargo.toml
@@ -3,7 +3,7 @@ members = ["security-adapters", "compliance", "guardrails", "runtime", "git-brok
resolver = "2"
[workspace.package]
-version = "0.1.0-beta.1"
+version = "0.1.0-beta.2"
edition = "2021"
rust-version = "1.96"
license = "MIT"
diff --git a/harness/desktop-starters/README.md b/harness/desktop-starters/README.md
index a4bb3928..91ebca6d 100644
--- a/harness/desktop-starters/README.md
+++ b/harness/desktop-starters/README.md
@@ -1,7 +1,7 @@
# Desktop app starters
Desktop scaffolder with registry dependencies by default and an explicit source
-checkout mode. Candidate: `[email protected]`; registry publication is
+checkout mode. Candidate: `[email protected]`; registry publication is
a separate release step. See the [installation guide](../../docs/harness/guides/installation.md).
```sh
diff --git a/harness/desktop-starters/package.json b/harness/desktop-starters/package.json
index 55310348..b5260fe5 100644
--- a/harness/desktop-starters/package.json
+++ b/harness/desktop-starters/package.json
@@ -1,6 +1,6 @@
{
"name": "create-openworker",
- "version": "0.1.0-beta.1",
+ "version": "0.1.0-beta.2",
"type": "module",
"bin": {
"create-openworker": "create.mjs"
diff --git a/harness/examples/quickstart/README.md b/harness/examples/quickstart/README.md
index a7a2562d..039f69ee 100644
--- a/harness/examples/quickstart/README.md
+++ b/harness/examples/quickstart/README.md
@@ -21,7 +21,7 @@ npm run web
Run one command per terminal. The web app opens at http://127.0.0.1:4352/ . The model credentials stay in Electron's main process or the web server. They are never forwarded to the renderer/browser.
-The source example uses a local SDK dependency until publication. Once `0.1.0-beta.1` is published, applications can install `@openworkerai/[email protected]` from npm, including its matching native package, instead of using this checkout and executable override.
+The source example uses a local SDK dependency until publication. Once `0.1.0-beta.2` is published, applications can install `@openworkerai/[email protected]` from npm, including its matching native package, instead of using this checkout and executable override.
## Desktop packaging
@@ -62,7 +62,7 @@ node scripts/export-context.mjs code /path/to/project /tmp/context.json
cargo run --manifest-path rust/Cargo.toml -- /tmp/context.json 'Explain the main components.'
```
-The Rust crate uses a local path for this source checkout. For registry use after publication, replace it with `openworker-sdk = "=0.1.0-beta.1"`. A UI can embed this lifecycle and render its event stream.
+The Rust crate uses a local path for this source checkout. For registry use after publication, replace it with `openworker-sdk = "=0.1.0-beta.2"`. A UI can embed this lifecycle and render its event stream.
## Verification
diff --git a/harness/examples/quickstart/package-lock.json b/harness/examples/quickstart/package-lock.json
index e8716a72..89577a28 100644
--- a/harness/examples/quickstart/package-lock.json
+++ b/harness/examples/quickstart/package-lock.json
@@ -23,7 +23,7 @@
},
"../../typescript-sdk": {
"name": "@openworkerai/harness-sdk",
- "version": "0.1.0-beta.1",
+ "version": "0.1.0-beta.2",
"license": "MIT",
"devDependencies": {
"@types/node": "^22.0.0",
diff --git a/harness/examples/quickstart/rust/Cargo.lock b/harness/examples/quickstart/rust/Cargo.lock
index 36028a0f..0ac52493 100644
--- a/harness/examples/quickstart/rust/Cargo.lock
+++ b/harness/examples/quickstart/rust/Cargo.lock
@@ -1556,7 +1556,7 @@ dependencies = [
[[package]]
name = "openworker-artifacts"
-version = "0.1.0-beta.1"
+version = "0.1.0-beta.2"
dependencies = [
"anyhow",
"async-stream",
@@ -1574,7 +1574,7 @@ dependencies = [
[[package]]
name = "openworker-compliance"
-version = "0.1.0-beta.1"
+version = "0.1.0-beta.2"
dependencies = [
"anyhow",
"serde",
@@ -1593,7 +1593,7 @@ dependencies = [
[[package]]
name = "openworker-guardrails"
-version = "0.1.0-beta.1"
+version = "0.1.0-beta.2"
dependencies = [
"anyhow",
"futures-util",
@@ -1606,7 +1606,7 @@ dependencies = [
[[package]]
name = "openworker-runtime"
-version = "0.1.0-beta.1"
+version = "0.1.0-beta.2"
dependencies = [
"anyhow",
"base64 0.22.1",
@@ -1641,7 +1641,7 @@ dependencies = [
[[package]]
name = "openworker-sdk"
-version = "0.1.0-beta.1"
+version = "0.1.0-beta.2"
dependencies = [
"anyhow",
"async-stream",
@@ -1662,7 +1662,7 @@ dependencies = [
[[package]]
name = "openworker-store-postgres"
-version = "0.1.0-beta.1"
+version = "0.1.0-beta.2"
dependencies = [
"anyhow",
"native-tls",
@@ -1681,7 +1681,7 @@ dependencies = [
[[package]]
name = "openworker-telemetry"
-version = "0.1.0-beta.1"
+version = "0.1.0-beta.2"
dependencies = [
"anyhow",
"async-trait",
@@ -1703,7 +1703,7 @@ dependencies = [
[[package]]
name = "openworker-tools"
-version = "0.1.0-beta.1"
+version = "0.1.0-beta.2"
dependencies = [
"anyhow",
"serde",
diff --git a/harness/harness-sdk/Cargo.toml b/harness/harness-sdk/Cargo.toml
index 962f07bd..252d857a 100644
--- a/harness/harness-sdk/Cargo.toml
+++ b/harness/harness-sdk/Cargo.toml
@@ -22,15 +22,15 @@ name = "openworker-harness"
path = "src/main.rs"
[dependencies]
-openworker-security-adapters = { version = "=0.1.0-beta.1", path = "../security-adapters", optional = true }
+openworker-security-adapters = { version = "=0.1.0-beta.2", path = "../security-adapters", optional = true }
reqwest = { version = "0.12", default-features = false, features = ["json", "stream", "rustls-tls"] }
anyhow = "1"
fs2 = "0.4"
rusqlite = { version = "0.32", features = ["bundled"] }
-openworker-store-postgres = { version = "=0.1.0-beta.1", path = "../store-postgres" }
-openworker-runtime = { version = "=0.1.0-beta.1", path = "../runtime", default-features = false }
-openworker-telemetry = { version = "=0.1.0-beta.1", path = "../telemetry", features = ["otlp"] }
-openworker-tools = { version = "=0.1.0-beta.1", path = "../tools-sdk" }
+openworker-store-postgres = { version = "=0.1.0-beta.2", path = "../store-postgres" }
+openworker-runtime = { version = "=0.1.0-beta.2", path = "../runtime", default-features = false }
+openworker-telemetry = { version = "=0.1.0-beta.2", path = "../telemetry", features = ["otlp"] }
+openworker-tools = { version = "=0.1.0-beta.2", path = "../tools-sdk" }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tokio = { version = "1", features = ["full"] }
diff --git a/harness/harness-sdk/README.md b/harness/harness-sdk/README.md
index 83355314..955290e0 100644
--- a/harness/harness-sdk/README.md
+++ b/harness/harness-sdk/README.md
@@ -1,6 +1,6 @@
# OpenWorker Harness SDK (development API)
-Registry candidate: **0.1.0-beta.1**. See the [installation guide](https://github.com/andrewyng/openworker/blob/openworker-harness-sdk/docs/harness/guides/installation.md) and [tested desktop QuickStart](https://github.com/andrewyng/openworker/blob/openworker-harness-sdk/docs/harness/guides/desktop.md). Registry publication is a separate release step; prepared tarballs are available for pre-publication testing.
+Registry candidate: **0.1.0-beta.2**. See the [installation guide](https://github.com/andrewyng/openworker/blob/openworker-harness-sdk/docs/harness/guides/installation.md) and [tested desktop QuickStart](https://github.com/andrewyng/openworker/blob/openworker-harness-sdk/docs/harness/guides/desktop.md). Registry publication is a separate release step; prepared tarballs are available for pre-publication testing.
One Rust client, two deployment backends, the same native engine. This is a beta
crate with an explicit SDK/runtime compatibility contract. It is distinct
diff --git a/harness/release/manifest.json b/harness/release/manifest.json
index 2a797ba8..d7d08356 100644
--- a/harness/release/manifest.json
+++ b/harness/release/manifest.json
@@ -1,5 +1,5 @@
{
- "version": "0.1.0-beta.1",
+ "version": "0.1.0-beta.2",
"protocol": "0.1",
"rustPackages": [
{
diff --git a/harness/runtime/Cargo.toml b/harness/runtime/Cargo.toml
index 8088f5ad..ef4d2f2e 100644
--- a/harness/runtime/Cargo.toml
+++ b/harness/runtime/Cargo.toml
@@ -22,10 +22,10 @@ compliance-export = ["compliance"]
test-fixtures = []
[dependencies]
-openworker-compliance = { version = "=0.1.0-beta.1", path = "../compliance" }
-openworker-guardrails = { version = "=0.1.0-beta.1", path = "../guardrails", default-features = false }
-openworker-telemetry = { version = "=0.1.0-beta.1", path = "../telemetry" }
-openworker-tools = { version = "=0.1.0-beta.1", path = "../tools-sdk" }
+openworker-compliance = { version = "=0.1.0-beta.2", path = "../compliance" }
+openworker-guardrails = { version = "=0.1.0-beta.2", path = "../guardrails", default-features = false }
+openworker-telemetry = { version = "=0.1.0-beta.2", path = "../telemetry" }
+openworker-tools = { version = "=0.1.0-beta.2", path = "../tools-sdk" }
anyhow = "1"
base64 = "0.22"
clap = { version = "4", features = ["derive"] }
diff --git a/harness/security-adapters/Cargo.toml b/harness/security-adapters/Cargo.toml
index a1a6dda3..0b3870d8 100644
--- a/harness/security-adapters/Cargo.toml
+++ b/harness/security-adapters/Cargo.toml
@@ -11,7 +11,7 @@ license.workspace = true
[dependencies]
anyhow = "1"
-openworker-guardrails = { version = "=0.1.0-beta.1", path = "../guardrails", default-features = false }
+openworker-guardrails = { version = "=0.1.0-beta.2", path = "../guardrails", default-features = false }
reqwest = { version = "0.12", default-features = false, features = ["json", "stream", "rustls-tls"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
diff --git a/harness/store-postgres/Cargo.toml b/harness/store-postgres/Cargo.toml
index f1766a57..1a812f88 100644
--- a/harness/store-postgres/Cargo.toml
+++ b/harness/store-postgres/Cargo.toml
@@ -26,9 +26,9 @@ path = "tests/support/recovery.rs"
required-features = ["test-support"]
[dependencies]
-openworker-artifacts = { version = "=0.1.0-beta.1", path = "../artifacts" }
-openworker-runtime = { version = "=0.1.0-beta.1", path = "../runtime", default-features = false }
-openworker-tools = { version = "=0.1.0-beta.1", path = "../tools-sdk", optional = true }
+openworker-artifacts = { version = "=0.1.0-beta.2", path = "../artifacts" }
+openworker-runtime = { version = "=0.1.0-beta.2", path = "../runtime", default-features = false }
+openworker-tools = { version = "=0.1.0-beta.2", path = "../tools-sdk", optional = true }
anyhow = "1"
postgres = { version = "0.19", features = ["with-serde_json-1"] }
postgres-native-tls = "0.5"
diff --git a/harness/typescript-sdk/README.md b/harness/typescript-sdk/README.md
index da7450d7..3156a213 100644
--- a/harness/typescript-sdk/README.md
+++ b/harness/typescript-sdk/README.md
@@ -1,6 +1,6 @@
# OpenWorker TypeScript Harness SDK
-Registry candidate: **0.1.0-beta.1**. After publication, install with `npm install @openworkerai/[email protected]`; the matching native runtime is selected automatically. Until then, use the locally prepared client and platform archives. See the [Desktop guide](https://openworker.com/docs/sdk/desktop/) and [app-building skill](https://github.com/andrewyng/openworker/tree/main/skills).
+Registry candidate: **0.1.0-beta.2**. After publication, install with `npm install @openworkerai/[email protected]`; the matching native runtime is selected automatically. Until then, use the locally prepared client and platform archives. See the [Desktop guide](https://openworker.com/docs/sdk/desktop/) and [app-building skill](https://github.com/andrewyng/openworker/tree/main/skills).
Beta API, Node.js 20+, ESM. Registry-ready source/tarball distribution. The Rust host owns model/tool execution, policy, persistence,
agent teams and run semantics. This package owns typed APIs and a managed private
@@ -259,7 +259,7 @@ prefer shared providers and the desktop facade above.
After publication:
```sh
-npm install @openworkerai/[email protected]
+npm install @openworkerai/[email protected]
```
The client installs the matching `@openworkerai/harness-runtime-<platform>-<arch>`
@@ -271,8 +271,8 @@ helper outside ASAR; `resolveRuntimeExecutable()` returns its installed path.
Before publication, install the prepared client and your platform archive together:
```sh
-npm install /absolute/release/openworkerai-harness-sdk-0.1.0-beta.1.tgz \
- /absolute/release/openworkerai-harness-runtime-darwin-arm64-0.1.0-beta.1.tgz
+npm install /absolute/release/openworkerai-harness-sdk-0.1.0-beta.2.tgz \
+ /absolute/release/openworkerai-harness-runtime-darwin-arm64-0.1.0-beta.2.tgz
```
Choose the actual platform/architecture. The source manifest intentionally remains
diff --git a/harness/typescript-sdk/package-lock.json b/harness/typescript-sdk/package-lock.json
index 037f8efc..2d6f539c 100644
--- a/harness/typescript-sdk/package-lock.json
+++ b/harness/typescript-sdk/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "@openworkerai/harness-sdk",
- "version": "0.1.0-beta.1",
+ "version": "0.1.0-beta.2",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "@openworkerai/harness-sdk",
- "version": "0.1.0-beta.1",
+ "version": "0.1.0-beta.2",
"license": "MIT",
"devDependencies": {
"@types/node": "^22.0.0",
diff --git a/harness/typescript-sdk/package.json b/harness/typescript-sdk/package.json
index b492dbaf..13cde785 100644
--- a/harness/typescript-sdk/package.json
+++ b/harness/typescript-sdk/package.json
@@ -1,6 +1,6 @@
{
"name": "@openworkerai/harness-sdk",
- "version": "0.1.0-beta.1",
+ "version": "0.1.0-beta.2",
"description": "Node.js client for the OpenWorker Rust harness over managed private stdio",
"type": "module",
"license": "MIT",
diff --git a/harness/typescript-sdk/src/version.ts b/harness/typescript-sdk/src/version.ts
index fe3fc0e3..23e5835b 100644
--- a/harness/typescript-sdk/src/version.ts
+++ b/harness/typescript-sdk/src/version.ts
@@ -1,2 +1,2 @@
// Must match release/manifest.json. Checked by release validation.
-export const SDK_VERSION = "0.1.0-beta.1";
+export const SDK_VERSION = "0.1.0-beta.2";
diff --git a/skills/README.md b/skills/README.md
index daa6465b..1d6b1e6d 100644
--- a/skills/README.md
+++ b/skills/README.md
@@ -5,9 +5,8 @@ applications with the OpenWorker Harness SDK. It includes version-matched SDK
snippets and separate Desktop/Web references. No OpenWorker checkout is required
for the packaged skill, and installing it does not install the SDK or a runtime.
-**Release candidate:** `@openworkerai/[email protected]` is prepared
-locally. The new `--global` option and Railway guidance require this release;
-until it is published, use the local candidate instructions below to try them.
+This skill release targets SDK `0.1.0-beta.2`, including provider caching,
+attempt-aware streaming and per-turn session options.
## Install the skill
@@ -29,7 +28,7 @@ on Windows and macOS, leaves global settings alone, and refuses to overwrite an
existing skill. Review/back up an existing installation before replacing it.
`references/installation.json` records the matching SDK version, without local
checkout paths or credentials. Use `sdkVersion` from that file for the SDK. Skill and SDK package versions may
-differ; this skill candidate targets SDK `0.1.0-beta.1`.
+differ; this skill release targets SDK `0.1.0-beta.2`.
### Across your projects
@@ -98,7 +97,7 @@ node skills/prepare.mjs /absolute/new-skills-candidate
Install the resulting archive into a temporary project or use it through npm exec:
```sh
-npm exec --package /absolute/new-skills-candidate/archives/openworkerai-build-with-sdk-skills-0.1.0-beta.2.tgz -- build-with-sdk-skills --agent codex --project /path/to/your-app
+npm exec --package /absolute/new-skills-candidate/archives/openworkerai-build-with-sdk-skills-0.1.0-beta.3.tgz -- build-with-sdk-skills --agent codex --project /path/to/your-app
```
The preparer never publishes. Source package manifests remain private; staged
diff --git a/skills/install.mjs b/skills/install.mjs
index fc22a390..de3caf54 100644
--- a/skills/install.mjs
+++ b/skills/install.mjs
@@ -7,7 +7,7 @@ import { homedir } from 'node:os';
import { parseArgs } from 'node:util';
const source = dirname(fileURLToPath(import.meta.url));
const usage = 'build-with-sdk-skills --agent codex|claude (--project /path/to/your-app | --global)';
-const files = ['SKILL.md','references/desktop.md','references/web.md','references/sdk.md','references/railway.md','assets/railway/Dockerfile','assets/railway/.dockerignore','agents/openai.yaml'];
+const files = ['SKILL.md','references/desktop.md','references/web.md','references/sdk.md','references/runtime-options.md','references/railway.md','assets/railway/Dockerfile','assets/railway/.dockerignore','agents/openai.yaml'];
function validate({agent, project, global: userWide = false}) {
if (!['codex','claude'].includes(agent) || typeof userWide !== 'boolean' ||
(project !== undefined && (typeof project !== 'string' || !project.trim())) ||
diff --git a/skills/openworker-apps/SKILL.md b/skills/openworker-apps/SKILL.md
index 66e5cd6e..f3b09295 100644
--- a/skills/openworker-apps/SKILL.md
+++ b/skills/openworker-apps/SKILL.md
@@ -11,6 +11,8 @@ Preserve their chosen UI framework, model and deployment target.
## Choose the track
- Read [SDK integration](references/sdk.md) for the shared lifecycle and package contract.
+- For provider configuration, retry-safe streaming, reasoning display, migrated
+ history or changing turn preferences, read [Runtime options](references/runtime-options.md).
- For desktop apps, read [Desktop](references/desktop.md).
- For browser/server apps, read [Web](references/web.md).
- For a Railway deployment, read [Railway](references/railway.md). Default to one
diff --git a/skills/openworker-apps/references/runtime-options.md b/skills/openworker-apps/references/runtime-options.md
new file mode 100644
index 00000000..65ed1d84
--- /dev/null
+++ b/skills/openworker-apps/references/runtime-options.md
@@ -0,0 +1,140 @@
+# Provider, session and streaming options
+
+These options require SDK and native runtime 0.1.0-beta.2 or later. Upgrade both;
+the published SDK installs its exact matching platform runtime automatically.
+If the app sets an explicit executable, update that binary too. Preserve existing
+agent identities unless intentionally changing their immutable definitions.
+
+## Providers and usage
+
+Anthropic prompt caching is enabled by default. Set `promptCaching: false` on
+provider registration to opt out. A short prompt may not reach the provider's
+cache threshold; zero cache hits alone do not indicate a broken cache.
+
+Chat Completions requests streaming usage by default. Set `streamUsage: false`
+only for endpoints that reject `stream_options.include_usage`. Missing usage is
+unknown, not zero cost. Use the run's `model_usage` events for reported tokens;
+calculate monetary cost only when the selected model's pricing is known.
+
+Use Google's OpenAI-compatible endpoint for Gemini; this is not a native Gemini
+adapter. Signed tool context survives ordinary durable-session resume. Never
+strip signatures from the internal history or reconstruct it from UI text.
+Use the exact model ID available to the user's provider account.
+
+```typescript
+import { Harness } from '@openworkerai/harness-sdk';
+
+export async function configureProviders(harness: Harness) {
+ await harness.setModelProvider({
+ name: 'Claude', api: 'anthropic',
+ credentials: { apiKeyEnv: 'ANTHROPIC_API_KEY', storage: 'memory' },
+ promptCaching: true,
+ // Add thinking only when supported by the chosen model:
+ // thinking: { type: 'adaptive' },
+ // or thinking: { type: 'enabled', budgetTokens: 2048 },
+ });
+ await harness.setModelProvider({
+ name: 'Gemini', api: 'chat-completions',
+ baseUrl: 'https://generativelanguage.googleapis.com/v1beta/openai',
+ credentials: { apiKeyEnv: 'GEMINI_API_KEY', storage: 'memory' },
+ });
+ await harness.setModelProvider({
+ name: 'Together', api: 'chat-completions',
+ baseUrl: 'https://api.together.ai/v1',
+ credentials: { apiKeyEnv: 'TOGETHER_API_KEY', storage: 'memory' },
+ });
+}
+```
+
+Register only providers the app uses. Provider credentials remain in the trusted
+Node process. Reasoning display is opt-in and separate from model generation:
+Anthropic needs an explicit supported `thinking` mode; OpenAI Responses requests
+available reasoning summaries; compatible providers may return `reasoning_content`.
+Do not promise that every model emits reasoning. Never expose private signatures
+or redacted thinking. Safety checks can withhold candidate output.
+
+## Turn preferences, migration and retry-safe display
+
+The following helper demonstrates the options together; choose only what the
+product needs. The UI callback replaces escaped text, rather than appending every
+delta. A failed model attempt is discarded by `AttemptOutput`. For no provisional
+text at all, use `bufferAttempts: true` (buffers each attempt, not the entire turn).
+
+```typescript
+import { AttemptOutput, Harness } from '@openworkerai/harness-sdk';
+
+export async function runGuide(
+ harness: Harness,
+ provider: string,
+ model: string,
+ userText: string,
+ preferences: string,
+ render: (answer: string, reasoning: string) => void,
+) {
+ const agent = harness.createAgent({
+ name: 'guide', instructions: 'Explain the supplied material clearly.',
+ defaultModel: { provider, name: model },
+ tools: [], planning: false, memory: false, scheduling: false,
+ builtinTools: { askUser: false, readHistory: false },
+ });
+ await agent.ready();
+ // Import only when migrating. For ordinary recovery, use resumeSession.
+ const session = await agent.newSession({ initialHistory: [
+ { type: 'user', text: 'I am learning about databases.' },
+ { type: 'assistant', text: 'We can start with indexes.' },
+ ] });
+ const display = new AttemptOutput();
+ const run = await session.send(userText, {
+ // Application-owned instructions, not untrusted user/document text.
+ instructionAddendum: preferences,
+ limits: {
+ maxModelCalls: 8, maxOutputTokens: 60000,
+ maxOutputTokensPerCall: 24000, summaryTokens: 512,
+ },
+ output: { reasoning: true, bufferAttempts: false },
+ });
+ for await (const event of run.events()) {
+ display.apply(event);
+ render(display.text, display.reasoning);
+ }
+ const result = await run.result();
+ if (result.status !== 'completed') {
+ display.interrupt();
+ render(display.text, display.reasoning);
+ // Handle pending approvals/questions when enabling tools. Log only safe
+ // structured diagnostics, not raw upstream bodies, prompts or credentials.
+ if (result.providerError) {
+ const { category, httpStatus, requestId, code } = result.providerError;
+ console.error({ category, httpStatus, requestId, code });
+ }
+ } else {
+ render(result.finalOutput ?? '', display.reasoning);
+ }
+ return { result, reference: session.reference() };
+}
+```
+
+Create one session per conversation in a real app and reuse it for later turns.
+The helper creates a new one only to illustrate migration. `instructionAddendum`
+is stored with the current turn, applies across retries and expires on the next
+turn. Before-model hooks inspect it; user-input guardrails do not treat it as user
+text. When supplying `submissionId`, retries must keep the same content/options.
+
+The per-call ceiling defaults to 8,192 tokens; the model must support any higher
+requested ceiling. The remaining total turn allowance can lower it. Increasing
+one ceiling does not increase the other. Limits can also be agent defaults.
+
+`initialHistory` accepts user/assistant text and completed `tool_call` / paired
+`tool_result` entries, never provider-private or system messages. Imported tools
+do not execute. Sanitize imported content: import does not retroactively run input
+or tool-result guardrails. Resume the original session when signed model context
+must be preserved. Imports are bounded (256 entries, 512,000 serialized bytes).
+
+A tool-free agent advertises no implicit tools. For an agent with application
+tools, `builtinTools` can independently disable `askUser` and `readHistory`.
+Changing these immutable settings requires a new agent identity/session.
+
+For UI activity, `model_activity` reports elapsed waiting time at most once every
+five seconds; it is not task progress. Match tool callback UI with
+`(sessionId, turnId, callId)`, not event arrival order. Do not retry side effects
+because a stream disconnects; resume the durable run and reconcile its outcome.
diff --git a/skills/openworker-apps/references/sdk.md b/skills/openworker-apps/references/sdk.md
index c7effec2..945f582f 100644
--- a/skills/openworker-apps/references/sdk.md
+++ b/skills/openworker-apps/references/sdk.md
@@ -72,28 +72,34 @@ Create one session for a conversation. Keep distinct documents, projects and use
separate according to the application's ownership rules.
```typescript
+import { AttemptOutput } from '@openworkerai/harness-sdk';
+
const session = await agent.newSession();
+const display = new AttemptOutput();
const run = await session.send('Source data:\n' + sourceText + '\n\nSummarize it.');
for await (const item of run.events()) {
- if (item.event.type === 'assistant_delta') {
- const data = item.event.data as { text?: string };
- if (typeof data.text === 'string') emitText(data.text);
- }
+ display.apply(item);
+ renderText(display.text); // Replace the displayed text; do not append.
}
const result = await run.result();
if (result.status !== 'completed') {
+ display.interrupt();
+ renderText(display.text);
throw new Error(`Run ended: ${result.status}`);
}
// result.finalOutput is the final text. Do not append it to already streamed
// text a second time; use it to replace/reconcile the displayed answer.
```
-`emitText` and `sourceText` belong to the application. Handle pending approval or
+`renderText` and `sourceText` belong to the application. Handle pending approval or
question interactions when enabling tools. A closed stream is not proof of a
successful run. Use `session.cancel()` for Stop, and call `harness.shutdown()`
once when the application exits. Retain `session.reference()` when the product
needs to resume a durable conversation via `agent.resumeSession(reference)`.
+For reasoning display, output buffering, provider usage and turn options, read
+[Runtime options](runtime-options.md).
+
## More APIs
Inspect the installed `@openworkerai/harness-sdk` declarations before adding tools, teams
diff --git a/skills/package.json b/skills/package.json
index af8fccd7..eeea3bb7 100644
--- a/skills/package.json
+++ b/skills/package.json
@@ -1,19 +1,33 @@
{
"name": "@openworkerai/build-with-sdk-skills",
- "version": "0.1.0-beta.2",
+ "version": "0.1.0-beta.3",
"description": "Install the OpenWorker app-building skill for Codex or Claude Code",
"type": "module",
"license": "MIT",
- "engines": { "node": ">=20" },
- "bin": { "build-with-sdk-skills": "install.mjs" },
- "files": ["install.mjs", "openworker-apps", "README.md", "LICENSE"],
- "scripts": { "test": "node --test install.test.mjs package.test.mjs" },
+ "engines": {
+ "node": ">=20"
+ },
+ "bin": {
+ "build-with-sdk-skills": "install.mjs"
+ },
+ "files": [
+ "install.mjs",
+ "openworker-apps",
+ "README.md",
+ "LICENSE"
+ ],
+ "scripts": {
+ "test": "node --test install.test.mjs package.test.mjs"
+ },
"repository": {
"type": "git",
"url": "git+https://github.com/andrewyng/openworker.git",
"directory": "skills"
},
- "publishConfig": { "access": "public", "tag": "beta" },
+ "publishConfig": {
+ "access": "public",
+ "tag": "beta"
+ },
"private": true,
- "openworkerSdkVersion": "0.1.0-beta.1"
+ "openworkerSdkVersion": "0.1.0-beta.2"
}
diff --git a/skills/snippets.test.mjs b/skills/snippets.test.mjs
new file mode 100644
index 00000000..de604101
--- /dev/null
+++ b/skills/snippets.test.mjs
@@ -0,0 +1,26 @@
+import test from 'node:test';
+import { mkdtemp, readFile, mkdir, symlink, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+test('runtime-options examples compile against the matching SDK declarations', async () => {
+ const sdk = resolve('harness/typescript-sdk');
+ const root = await mkdtemp(join(tmpdir(), 'ow-skill-snippets-'));
+ try {
+ await mkdir(join(root, 'node_modules/@openworkerai'), { recursive: true });
+ await symlink(sdk, join(root, 'node_modules/@openworkerai/harness-sdk'), 'junction');
+ await writeFile(join(root, 'package.json'), '{"type":"module"}');
+ const text = await readFile('skills/openworker-apps/references/runtime-options.md', 'utf8');
+ const files = [];
+ for (const [index, match] of [...text.matchAll(/```typescript\r?\n([\s\S]*?)```/g)].entries()) {
+ const file = join(root, `example-${index}.ts`);
+ await writeFile(file, match[1]);
+ files.push(file);
+ }
+ if (!files.length) throw Error('No examples found');
+ execFileSync(process.execPath, [join(sdk, 'node_modules/typescript/bin/tsc'), ...files,
+ '--noEmit', '--strict', '--skipLibCheck', '--target', 'es2022', '--module', 'nodenext',
+ '--typeRoots', join(sdk, 'node_modules/@types')], { stdio: 'pipe' });
+ } finally { await rm(root, { recursive: true, force: true }); }
+});