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.ymlindex 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 installationrun: 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.mjsdiff --git a/harness/Cargo.lock b/harness/Cargo.lockindex 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.tomlindex fd288c4f..6de2ff71 100644--- a/harness/Cargo.toml+++ b/harness/Cargo.toml@@ -3,7 +3,7 @@ members = ["security-adapters", "compliance", "guardrails", "runtime", "git-brokresolver = "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.mdindex a4bb3928..91ebca6d 100644--- a/harness/desktop-starters/README.md+++ b/harness/desktop-starters/README.md@@ -1,7 +1,7 @@# Desktop app startersDesktop 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 isa separate release step. See the [installation guide](../../docs/harness/guides/installation.md).```shdiff --git a/harness/desktop-starters/package.json b/harness/desktop-starters/package.jsonindex 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.mdindex a7a2562d..039f69ee 100644--- a/harness/examples/quickstart/README.md+++ b/harness/examples/quickstart/README.md@@ -21,7 +21,7 @@ npm run webRun 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.jsoncargo 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.## Verificationdiff --git a/harness/examples/quickstart/package-lock.json b/harness/examples/quickstart/package-lock.jsonindex 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.lockindex 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.tomlindex 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.mdindex 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 betacrate with an explicit SDK/runtime compatibility contract. It is distinctdiff --git a/harness/release/manifest.json b/harness/release/manifest.jsonindex 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.tomlindex 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.tomlindex 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.tomlindex 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.mdindex 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 remainsdiff --git a/harness/typescript-sdk/package-lock.json b/harness/typescript-sdk/package-lock.jsonindex 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.jsonindex 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.tsindex 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.mdindex 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 SDKsnippets and separate Desktop/Web references. No OpenWorker checkout is requiredfor 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 anexisting skill. Review/back up an existing installation before replacing it.`references/installation.json` records the matching SDK version, without localcheckout 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-candidateInstall 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; stageddiff --git a/skills/install.mjs b/skills/install.mjsindex 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.mdindex 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 onediff --git a/skills/openworker-apps/references/runtime-options.md b/skills/openworker-apps/references/runtime-options.mdnew file mode 100644index 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.mdindex 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 useseparate 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 orquestion interactions when enabling tools. A closed stream is not proof of asuccessful run. Use `session.cancel()` for Stop, and call `harness.shutdown()`once when the application exits. Retain `session.reference()` when the productneeds 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 APIsInspect the installed `@openworkerai/harness-sdk` declarations before adding tools, teamsdiff --git a/skills/package.json b/skills/package.jsonindex 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.mjsnew file mode 100644index 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 }); }+});