Python
docs: lead SDK onboarding with architecture and builder skill
Rohit P5b2007b9b4ee
diff --git a/README.md b/README.mdindex 13eff31e..123a6b4e 100644--- a/README.md+++ b/README.md@@ -41,7 +41,7 @@ Bring agentic capabilities to your own desktop app, web app or local utility. BuUse the TypeScript SDK from npm, or embed the Rust engine in your application. Start with one agent. Add sub-agents, teams, OpenShell sandboxing and observability as your application grows.```sh-npm install --save-exact @openworkerai/[email protected]+npm install @openworkerai/harness-sdk```[**Explore the Harness SDK →**](harness/README.md) ·diff --git a/harness/README.md b/harness/README.mdindex 367e2c4c..841398f0 100644--- a/harness/README.md+++ b/harness/README.md@@ -4,23 +4,94 @@Build a document assistant, a file-organizing utility or a coding app with agents that can use tools and work together. Keep your interface and product workflow; OpenWorker manages the agent loop, model calls, approvals and durable sessions.-<p align="center"><a href="#build-your-first-agent">Get started</a> · <a href="https://openworker.com/docs/sdk/">Documentation</a> · <a href="#build-with-your-coding-agent">Builder skill</a> · <a href="#choose-an-example-app">Example apps</a></p>+<p align="center"><a href="#build-with-your-coding-agent">Get started</a> · <a href="https://openworker.com/docs/sdk/">Documentation</a> · <a href="#build-your-first-agent-by-writing-code-yourself">SDK reference</a> · <a href="#choose-an-example-app">Example apps</a></p>> **Under active development.** Please try the SDK and [open issues](https://github.com/andrewyng/openworker/issues) for bugs and feature requests. Please hold off on SDK pull requests while the API is evolving.-## Build your first agent+<a id="your-app-and-the-harness"></a>++## How it fits into your app++Your app owns the UI, authentication and user/session ownership. It chooses the models, tools and policies. One Rust engine powers both SDKs: TypeScript manages it as a child process; Rust can embed it in-process. Browser code calls your application server or desktop IPC.++++OpenShell isolates configured shell/file execution while the agent loop remains in the trusted harness. Application callbacks still run with your application’s privileges. See [execution boundaries](../docs/harness/guides/openshell.md).++The existing OpenWorker Desktop App uses its separate Python engine. This SDK provides the Rust engine for applications you build.++<a id="build-with-codex-or-claude-code"></a>++## Build with your coding agent++Install the builder skill in your app project:++```sh+npx @openworkerai/openworker-harness-builder --agent claude --project .+```-Use the code below, or [build with your coding agent](#build-with-your-coding-agent). You can start locally without a service cluster.+Use `--agent codex` for Codex, or replace `--project .` with `--global` for all your projects. Open a new coding-agent session and give it a concrete task:++> Use the openworker-harness-builder skill to build a local file-organizing app. Start with ten sample text files in a new demo directory. Restrict its file tools to that directory, ask me before creating subdirectories or moving files, and show tool activity as the agent works. Run the tests and explain how to launch it.++The skill supplies SDK instructions and runnable examples; you do not need to clone this repository. See the [skill guide](../skills/README.md) for updates, replacement backups and the tested SDK version.-### Write the code yourself+<a id="build-your-first-agent"></a>-Requires Node.js 20+ with ESM. npm includes the matching native runtime; no Rust compiler or Python installation is needed.+## Build your first agent by writing code yourself++We recommend building with a [coding agent and the builder skill](#build-with-your-coding-agent). The steps below serve as a quick reference, showing how little code it takes to start the harness in your app, create an agent and run a conversation.++Install the SDK:```sh-npm install --save-exact @openworkerai/[email protected]+npm install @openworkerai/harness-sdk+```++### 1. Start the harness and connect a model++Your app starts the harness once and supplies its model credentials. This text-only example uses OpenAI and does not need a sandbox.++```typescript+const harness = await Harness.start({+ stateDir: resolve('.openworker-state'), sandbox: 'off',+});+await harness.setModelProvider({+ name: 'OpenAI', api: 'responses',+ baseUrl: process.env.OPENWORKER_MODEL_URL ?? 'https://api.openai.com/v1',+ credentials: { apiKeyEnv: 'OPENAI_API_KEY', storage: 'memory' },+});```-Save this as `agent.mjs`. It connects a model, creates an agent and runs its first request:+### 2. Define the agent++Give the agent instructions and select its model. Start without tools; add your application's tools when it needs to take actions.++```typescript+const agent = harness.createAgent({+ name: 'first-agent-v1', instructions: 'Give concise, helpful answers.',+ defaultModel: { provider: 'OpenAI', name: model },+ tools: [], planning: false, memory: false, scheduling: false,+});+```++### 3. Start a conversation++Create a session, send a request and display the answer. Reuse the session for follow-up messages.++```typescript+const session = await agent.newSession();+const result = await session.run('Suggest three names for a file-organizing app.');+if (result.status !== 'completed') throw new Error(`Run ended: ${result.status}`);+console.log(result.finalOutput);+```++<details>+<summary>Complete runnable example and setup</summary>++Save as `agent.mjs`. In a private env file outside your project, set `OPENAI_API_KEY` to your API key and `OPENWORKER_MODEL` to an exact model ID available to your account. The complete example includes imports and shuts down the harness even if a request fails.++<!-- complete-first-agent -->```typescriptimport { resolve } from 'node:path';@@ -51,33 +122,19 @@ try {}```-In a private env file outside your project, set `OPENAI_API_KEY` to your API key and `OPENWORKER_MODEL` to an exact model ID available to your account. Then run:+<!-- /complete-first-agent -->```shnode --env-file=/path/to/private.env agent.mjs```-The program prints the agent’s answer. `OPENWORKER_MODEL_URL` optionally selects another Responses-compatible endpoint. See [models and credentials](../docs/harness/guides/providers.md) for Anthropic, other providers and local models.+`OPENWORKER_MODEL_URL` optionally selects another Responses-compatible endpoint. The SDK runs in your Node process, Electron main process or application server; npm includes the matching Rust runtime. See the [TypeScript quickstart](typescript-sdk/README.md) for runtime requirements and lifecycle details.-This first agent has no tools and explicitly disables sandboxing. When adding tools, choose their execution boundary: application callbacks retain your app’s privileges, and a workspace path alone does not confine filesystem access. Start with the [file-organizer example](../skills/openworker-harness-builder/references/local-script.md) for scoped tools and human approvals.--**Using Rust?** Follow the [complete Rust quickstart](harness-sdk/README.md) to embed the engine from a pinned checkout. It includes the current native-helper setup. The [TypeScript package README](typescript-sdk/README.md) covers application lifecycle and integration details.--<a id="build-with-codex-or-claude-code"></a>--### Build with your coding agent--Install the builder skill in your app project:--```sh-npx @openworkerai/openworker-harness-builder --agent claude --project .-```+</details>-Use `--agent codex` for Codex, or replace `--project .` with `--global` for all your projects. Open a new coding-agent session and give it a concrete task:+For other providers, see [models and credentials](../docs/harness/guides/providers.md). For a native app, follow the [Rust quickstart](harness-sdk/README.md).-> Use the openworker-harness-builder skill to build a local file-organizing app. Start with ten sample text files in a new demo directory. Restrict its file tools to that directory, ask me before creating subdirectories or moving files, and show tool activity as the agent works. Run the tests and explain how to launch it.--The skill supplies SDK instructions and runnable examples; you do not need to clone this repository. See the [skill guide](../skills/README.md) for updates, replacement backups and the tested SDK version.+When adding tools, choose their execution boundary: application callbacks retain your app’s privileges, and a workspace path alone does not confine filesystem access. The [file-organizer example](../skills/openworker-harness-builder/references/local-script.md) demonstrates scoped tools and human approvals.<a id="choose-your-starting-point"></a><a id="try-an-example"></a>@@ -93,10 +150,6 @@ The skill supplies SDK instructions and runnable examples; you do not need to clCode Atlas and PDF Notes share `examples/quickstart/`; they are two complete TypeScript apps. The file organizer is bundled with the skill. The checkout examples use the local SDK and need the runtime setup described in their READMEs.---*Code Atlas example UI, shown with deterministic test data.*-<a id="what-your-application-gains"></a>## What the SDK handles for you@@ -111,18 +164,6 @@ Code Atlas and PDF Notes share `examples/quickstart/`; they are two complete Typ| **A choice of models** | Cloud and local providers with application-owned credentials. [Models](../docs/harness/guides/providers.md) || **Visibility into each run** | Opt-in turn traces, token usage and telemetry export to tools such as Langfuse. [Observability](../docs/harness/guides/observability.md) |-<a id="your-app-and-the-harness"></a>--## How it fits into your app--Your app owns the UI, authentication and user/session ownership. It chooses the models, tools and policies. One Rust engine powers both SDKs: TypeScript manages it as a child process; Rust can embed it in-process. Browser code calls your application server or desktop IPC.----OpenShell isolates configured shell/file execution while the agent loop remains in the trusted harness. Application callbacks still run with your application’s privileges. See [execution boundaries](../docs/harness/guides/openshell.md).--The existing OpenWorker Desktop App uses its separate Python engine. This SDK provides the Rust engine for applications you build.-<a id="deployment-and-operations"></a>## Deployment and observability@@ -159,7 +200,7 @@ Use the [TypeScript](typescript-sdk/README.md) or [Rust](harness-sdk/README.md)<details><summary>Versions and native runtime compatibility</summary>-The npm client **0.1.0-beta.4** uses native runtime **0.1.0-beta.3**. npm installs the matching platform package automatically; keep optional dependencies enabled. Source manifests and published package versions can differ. Follow the [release and compatibility guide](../docs/harness/guides/releases.md) when pinning or upgrading, rather than inferring registry availability from a source version string.+npm installs the matching platform runtime package automatically; keep optional dependencies enabled. Source manifests and published package versions can differ. Follow the [release and compatibility guide](../docs/harness/guides/releases.md) when pinning or upgrading, rather than inferring registry availability from a source version string.Rust applications currently use a pinned source checkout. See the [Rust quickstart](harness-sdk/README.md); npm publication does not imply Cargo registry publication.diff --git a/harness/typescript-sdk/README.md b/harness/typescript-sdk/README.mdindex 967cff99..bd4a977d 100644--- a/harness/typescript-sdk/README.md+++ b/harness/typescript-sdk/README.md@@ -9,7 +9,7 @@ OpenWorker manages the agent loop.## Install```sh-npm install --save-exact @openworkerai/[email protected]+npm install @openworkerai/harness-sdk```Requires Node.js 20+ and ESM. This documentation-only client release uses thediff --git a/skills/snippets.test.mjs b/skills/snippets.test.mjsindex b18989b1..3dd9ff8f 100644--- a/skills/snippets.test.mjs+++ b/skills/snippets.test.mjs@@ -13,14 +13,19 @@ test('Skill, SDK READMEs and shared guide examples compile against the SDK declaawait writeFile(join(root, 'package.json'), '{"type":"module"}');const readme = await readFile(join(sdk,'README.md'),'utf8');const landing = await readFile('harness/README.md','utf8');+ const landingParts = [...landing.matchAll(/```typescript\r?\n([\s\S]*?)```/g)].map(match => match[1]);+ if (landingParts.length !== 4) throw Error('Expected three SDK steps and one complete example');+ // Compile the reference steps together, supplying only their shared imports/model.+ const reference = "import { resolve } from 'node:path';\nimport { Harness } from '@openworkerai/harness-sdk';\nconst model = 'fixture';\n" + landingParts.slice(0, 3).join('\n');+ await writeFile(join(root, 'landing-reference.ts'), reference);const streaming = await readFile('docs/harness/guides/streaming.md','utf8');const approvalSection = streaming.split('### Stream, approve and continue the same turn')[1];if (!approvalSection) throw Error('Missing shared streaming approval loop');const tools = await readFile('docs/harness/guides/tools.md','utf8');const callbackSection = tools.split('## Register an application callback')[1]?.split('## Tool names and directory scope')[0];if (!callbackSection) throw Error('Missing app callback example');- const text = (await Promise.all(['runtime-options.md','subagents.md'].map(name=>readFile('skills/openworker-harness-builder/references/'+name,'utf8')))).join('\n')+'\n'+readme+'\n'+landing+'\n'+approvalSection+'\n'+callbackSection;- const files = [];+ const text = (await Promise.all(['runtime-options.md','subagents.md'].map(name=>readFile('skills/openworker-harness-builder/references/'+name,'utf8')))).join('\n')+'\n'+readme+'\n```typescript\n'+landingParts[3]+'\n```\n'+approvalSection+'\n'+callbackSection;+ const files = [join(root, 'landing-reference.ts')];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]);