Python
docs: improve Desktop App and SDK getting started guides
Rohit P93877871a37d
diff --git a/README.md b/README.mdindex 0dbb983c..13eff31e 100644--- a/README.md+++ b/README.md@@ -22,10 +22,10 @@ It runs on your machine. Bring your own model key or run locally with Ollama, an<a id="download"></a>-[**⬇ macOS (Apple Silicon)**](https://download.openworker.com/mac)+[⬇ macOS (Apple Silicon)](https://download.openworker.com/mac)<sub>macOS 12+ · signed & notarized · auto-updates</sub>-[**⬇ Windows 10/11 (x64)**](https://download.openworker.com/windows)+[⬇ Windows 10/11 (x64)](https://download.openworker.com/windows)<sub>builds are not yet code-signed, so SmartScreen will warn; signing is in progress</sub>Open the app, add a model key (or point it at Ollama), and ask for something real.@@ -49,44 +49,50 @@ npm install --save-exact @openworkerai/[email protected][Web guide](docs/harness/guides/server.md) ·[Build with Codex or Claude Code](skills/README.md)-## Desktop App use cases+The rest of this README focuses on the OpenWorker Desktop App. For SDK documentation, continue with the [Harness SDK README](harness/README.md).-Pick a coworker, point it at real work, get a finished deliverable:+<a id="use-cases"></a>+<a id="desktop-app-use-cases"></a>+<a id="what-it-can-do"></a>-- **Security review** - scan a codebase and its dependencies for real risk. Findings come from deterministic scanners (like semgrep) plus model reasoning; proposed fixes are re-scanned and diff-reviewed before you approve them - the fixer is never the only checker.-- **Cloud posture** - audit cloud configuration against common misconfiguration classes and draft the remediation plan.-- **Incident triage** - work a security or ops incident: gather context across your tools, draft the timeline, prepare the report.-- **Everyday work** - prep a customer call from your CRM and inbox, turn scattered notes into a shippable plan, produce documents and spreadsheets, keep your calendar and Slack threads handled.-- **Standing automations** - a morning brief, a weekly report, a watch over a channel - on a schedule, with full transcripts.+## What you can do with the Desktop App-Specialist coworkers arrive with the tools, working style, and check-ins for one job already set up. Security coworkers ship first.+| Your work | How OpenWorker helps |+|---|---|+| **Research and create** | Turn notes, files and research into briefs, documents, spreadsheets and reports. |+| **Review security risks** | Scan code and dependencies, review cloud configuration, and investigate incidents. Proposed code fixes are re-scanned and reviewed before approval. |+| **Work across your tools** | Bring together GitHub, Slack, email, calendars and other connected apps. Add tools through MCP. |+| **Delegate from Slack** | Mention `@OpenWorker`; the task runs on your desktop and the reply returns to the thread. |+| **Automate recurring work** | Schedule morning briefs, weekly reports and other repeatable tasks, with transcripts to review. |+| **Choose your model** | Connect a cloud provider or use a local model through Ollama and other compatible servers. |+| **Control agent actions** | Review approvals, inspect recorded actions, and isolate supported commands with OpenShell or platform sandboxing. |++Specialist coworkers come with tools and instructions for a particular job. Security coworkers ship first.<a id="how-it-works"></a>+<a id="how-the-desktop-app-works"></a>-## How the Desktop App works+## Try your first task-1. Tell the OpenWorker Desktop App the outcome you want - "prepare a customer brief," "untangle my calendar," "draft a report," "check where the release stands across Jira and GitHub."-2. It breaks the task into steps and works across your desktop, files, and connected apps.-3. Before anything consequential - sending a message, changing a calendar, running a command - it checks in and you approve or redirect.-4. You get the finished deliverable, not a to-do list.+Start with a folder of meeting notes. No connected apps are needed for this example.-The Desktop App uses a Python agent engine. The Harness SDK provides a separate Rust engine for applications you build.+1. **Choose a model.** Open **Settings → Models & Keys** and connect a provider or local model.+2. **Choose your working folder.** Give the session access to a folder containing a few text or Markdown notes.+3. **Ask for a brief.** Paste the request below, follow the tool activity, and review any approval requests before continuing.-Under the hood:+> Read the meeting notes in this folder. Create a one-page brief with the key decisions, open questions and next steps. Save it as `brief.md`. Leave the original notes unchanged and ask before writing the brief.-```text-┌────────────────────────────────────────────────┐-│ OpenWorker Desktop App │ native shell + GUI-├────────────────────────────────────────────────┤-│ local agent server (Python) │ engine · tools · connectors - built on aisuite-├───────────────┬────────────────┬───────────────┤-│ your files │ your tools │ your model │ everything runs with your keys,-│ & terminal │ 25+ connectors │ any provider │ on your machine-└───────────────┴────────────────┴───────────────┘-```+++Open `brief.md` in the working folder and review it. Continue in the same session: “Make the next steps more specific, and flag anything without an owner.”## Governed by design+The Desktop App combines approvals, recorded tool activity and optional sandboxing. You can review proposed actions and decide how much autonomy to allow.++<details>+<summary>How approvals, audit trails and sandboxing work</summary>+Governance is the architecture, not a plugin - the agent can't grant itself new permissions, and no prompt can talk it past a gate. Four tiers, all in this repo:1. **Hard floors.** A set of dangerous and irreversible operations is human-only, always. No mode - including full auto-approve - lowers these floors; they always escalate to you.@@ -97,34 +103,13 @@ Governance is the architecture, not a plugin - the agent can't grant itself newUnattended runs never self-approve: their asks park in an inbox until a human answers. Found a vulnerability? See [SECURITY.md](SECURITY.md).-## What it can do--- **Produce real deliverables** - documents, spreadsheets, reports, and web pages land as files you can open and share.-- **Work from Slack** - mention `@OpenWorker` in a channel; a session opens on your desktop, the work happens with your tools, and the answer comes back as a thread reply.-- **Use your everyday tools** - 25+ integrations including GitHub, Slack, Jira, Notion, Linear, HubSpot, Outlook, monday.com, Gmail, and Google Calendar, plus your **terminal and local files**. Any tool reachable over [MCP](https://modelcontextprotocol.io/) plugs in too, with per-tool control.-- **Run on a schedule** - automations for recurring work: a morning brief, a weekly report, a standing watch over a channel. Runs land in the app with full transcripts.-- **Run commands in a sandbox** - turn on [NVIDIA OpenShell](docs/openshell.md) for a machine and every agent's shell and file tools run in their own Linux container, with the session's folders and an allow-listed network and nothing else; on a Mac, the [built-in sandbox](docs/macos-sandbox.md) does the same with nothing to install, and on Windows a [hidden local account](docs/windows-sandbox.md) does.-- **Ask before acting** - writes, sends, and shell commands are approval-gated, with an optional auto-approve mode that still escalates anything uncertain - see [Governed by design](#governed-by-design).+</details>## Bring your own model-In the OpenWorker Desktop App, model access is yours: pick a provider, paste your key, switch anytime. Supported out of the box:--**OpenAI · Azure OpenAI · Anthropic · Google Gemini · BytePlus Ark · Volcengine Ark Agent Plan · Atlas Cloud · Inkling (Thinking Machines) · GLM (Z.ai) · DeepSeek · Kimi (Moonshot) · Qwen · MiniMax · Mistral · Grok (xAI) · Solar (Upstage) · Cohere** - plus aggregators **OrcaRouter**, **OpenRouter** and **Hugging Face Inference Providers**, open-weight models via **Together**, **Fireworks**, **Cerebras** and **SiliconFlow**, and fully local models via **Ollama**, llama.cpp, vLLM, LM Studio, Jan, Docker Model Runner or mlx-lm.--A curated model list marks what we've verified for tool-calling work. Adding any model string works at your own risk.--Azure OpenAI uses your own resource: paste its endpoint and key (or set `AZURE_OPENAI_API_KEY`), then add your deployment names as models — on Azure the model id is the deployment name.--Another OpenAI-compatible server — a gateway, a proxy, a vendor not listed? In **Settings ▸ Models & Keys**, the **Add an OpenAI-compatible provider** box at the end of the API-keys group takes a name, its endpoint and key; it becomes its own card, and its models are selected as `<prefix>:<model-id>` (the prefix is derived from the name). Type the model ids, or fetch them from the server when it lists them.+Connect OpenAI, Anthropic, Google Gemini, OpenRouter and other providers, or use a local model through Ollama, LM Studio, llama.cpp or vLLM. Choose and switch models in **Settings → Models & Keys**.-OpenRouter comes two ways under **Settings → Models & Keys**: **OpenRouter** (API-keys) takes a key you paste; **OpenRouter account** (Subscriptions) signs you in-through the browser and uses your OpenRouter credits — the key OpenRouter issues-stays on this computer. On a remote backend choose **Use a manual code** and paste-the code OpenRouter shows. Each card is its own provider with its own models, so-disconnecting the account never falls back to a pasted key. To revoke the issued-key on OpenRouter's side, use the **Manage or revoke keys on OpenRouter** link.+See [Desktop App model setup](docs/desktop-models.md) for provider options, account connections and custom endpoints. SDK developers can use the separate [models and credentials guide](docs/harness/guides/providers.md).<a id="privacy"></a>@@ -132,10 +117,42 @@ key on OpenRouter's side, use the **Manage or revoke keys on OpenRouter** link.The OpenWorker Desktop App is local-first. Everything lives on your machine: the agent loop, your conversations, connector tokens, and model keys - all in the app's local secret store. The only cloud piece is a small service that brokers OAuth handshakes for connectors. You can always use the App without signing-in - use the connectors via manually-created credentials/API-keys.+## Documentation++| Start here | What you’ll find |+|---|---|+| [Desktop App model setup](docs/desktop-models.md) | Cloud providers, OpenRouter accounts and custom endpoints. |+| [Local models](docs/local-servers.md) | Connect models running on your own hardware. |+| [Approvals and safety](#governed-by-design) | How the Desktop App handles permissions and records actions. |+| [NVIDIA OpenShell](docs/openshell.md) | Set up sandboxed command and file execution for the Desktop App. |+| [Harness SDK](harness/README.md) | SDK installation, architecture and examples. |+| [Build a desktop app](docs/harness/guides/desktop.md) · [Build a web app](docs/harness/guides/server.md) | Learn the SDK through working applications. |+| [App-building skill](skills/README.md) | Build with Codex or Claude Code. |+| [SDK troubleshooting](docs/harness/guides/troubleshooting.md) | Diagnose SDK setup and runtime problems. |+<a id="run-from-source"></a>## Run the Desktop App from source+<details>+<summary>Development setup and architecture</summary>++The Desktop App uses a Python agent engine. The Harness SDK provides a separate Rust engine for applications you build.++Under the hood:++```text+┌────────────────────────────────────────────────┐+│ OpenWorker Desktop App │ native shell + GUI+├────────────────────────────────────────────────┤+│ local agent server (Python) │ engine · tools · connectors - built on aisuite+├───────────────┬────────────────┬───────────────┤+│ your files │ your tools │ your model │ everything runs with your keys,+│ & terminal │ 25+ connectors │ any provider │ on your machine+└───────────────┴────────────────┴───────────────┘+```++Prerequisites: Python 3.10+, Node 20+, and (for the desktop shell) the Rust toolchain via [rustup](https://rustup.rs/).```shell@@ -165,6 +182,8 @@ To run the full desktop app instead of the browser UI, replace step 3 with `npmTests: `.venv/bin/pytest` (server), `npm test` and `npm run e2e` in `surfaces/gui` (GUI unit + hermetic end-to-end). Desktop bundles are built with `packaging/build_dmg.sh` / `packaging/build_windows.ps1`.+</details>+## Repository layout| Directory | What's in it |diff --git a/docs/assets/first-task.svg b/docs/assets/first-task.svgnew file mode 100644index 00000000..6b414c39--- /dev/null+++ b/docs/assets/first-task.svg@@ -0,0 +1,37 @@+<svg xmlns="http://www.w3.org/2000/svg" width="1000" height="300" viewBox="0 0 1000 300" role="img" aria-labelledby="title desc">+ <title id="title">From meeting notes to a brief</title>+ <desc id="desc">Illustrative workflow: give OpenWorker meeting notes, review its proposed write, then open brief.md with decisions, questions and next steps.</desc>+ <rect width="1000" height="300" rx="20" fill="#f6f7f9"/>+ <g font-family="-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif">+ <text x="32" y="36" font-size="13" fill="#667085">EXAMPLE WORKFLOW</text>+ <g fill="white" stroke="#e1e4e8">+ <rect x="32" y="58" width="280" height="208" rx="14"/>+ <rect x="360" y="58" width="280" height="208" rx="14"/>+ <rect x="688" y="58" width="280" height="208" rx="14"/>+ </g>+ <g fill="none" stroke="#8c95a3" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round">+ <path d="M324 160h24m-6-6 6 6-6 6M652 160h24m-6-6 6 6-6 6"/>+ <path d="M56 104V86h13l5 5h22v25H56v-12z"/>+ <path d="M384 88h30v24h-30z m7 8 4 4 9-9"/>+ <path d="M712 84h20l10 10v24h-30z M732 84v11h10 M719 102h16 M719 109h12"/>+ </g>+ <g fill="#1d232b" font-size="21" font-weight="600">+ <text x="56" y="151">Your notes</text>+ <text x="384" y="151">Your approval</text>+ <text x="712" y="151">Your brief</text>+ </g>+ <g fill="#525d6b" font-size="15">+ <text x="56" y="181">Meeting notes in a folder</text>+ <text x="56" y="204">you choose.</text>+ <text x="384" y="181">Review the proposed write</text>+ <text x="384" y="204">before it goes ahead.</text>+ <text x="712" y="181">Decisions, open questions</text>+ <text x="712" y="204">and next steps.</text>+ </g>+ <g font-size="13" fill="#2463b4">+ <text x="56" y="242">Read the source material</text>+ <text x="384" y="242">Approve or redirect</text>+ <text x="712" y="242">Open brief.md · refine together</text>+ </g>+ </g>+</svg>diff --git a/docs/desktop-models.md b/docs/desktop-models.mdnew file mode 100644index 00000000..1e728597--- /dev/null+++ b/docs/desktop-models.md@@ -0,0 +1,25 @@+# Connect a model in the Desktop App++In the OpenWorker Desktop App, model access is yours: pick a provider, paste your key, switch anytime. Supported out of the box:++**OpenAI · Azure OpenAI · Anthropic · Google Gemini · BytePlus Ark · Volcengine Ark Agent Plan · Atlas Cloud · Inkling (Thinking Machines) · GLM (Z.ai) · DeepSeek · Kimi (Moonshot) · Qwen · MiniMax · Mistral · Grok (xAI) · Solar (Upstage) · Cohere** - plus aggregators **OrcaRouter**, **OpenRouter** and **Hugging Face Inference Providers**, open-weight models via **Together**, **Fireworks**, **Cerebras** and **SiliconFlow**, and fully local models via **Ollama**, llama.cpp, vLLM, LM Studio, Jan, Docker Model Runner or mlx-lm.++A curated model list marks what we've verified for tool-calling work. Adding any model string works at your own risk.++Azure OpenAI uses your own resource: paste its endpoint and key (or set `AZURE_OPENAI_API_KEY`), then add your deployment names as models — on Azure the model id is the deployment name.++Another OpenAI-compatible server — a gateway, a proxy, a vendor not listed? In **Settings ▸ Models & Keys**, the **Add an OpenAI-compatible provider** box at the end of the API-keys group takes a name, its endpoint and key; it becomes its own card, and its models are selected as `<prefix>:<model-id>` (the prefix is derived from the name). Type the model ids, or fetch them from the server when it lists them.++OpenRouter comes two ways under **Settings → Models & Keys**: **OpenRouter** (API+keys) takes a key you paste; **OpenRouter account** (Subscriptions) signs you in+through the browser and uses your OpenRouter credits — the key OpenRouter issues+stays on this computer. On a remote backend choose **Use a manual code** and paste+the code OpenRouter shows. Each card is its own provider with its own models, so+disconnecting the account never falls back to a pasted key. To revoke the issued+key on OpenRouter's side, use the **Manage or revoke keys on OpenRouter** link.++## Next steps++- [Local model servers](local-servers.md)+- [Per-model settings](model-settings.md)+- [Back to the Desktop App walkthrough](../README.md#try-your-first-task)diff --git a/harness/README.md b/harness/README.mdindex bd678e27..367e2c4c 100644--- a/harness/README.md+++ b/harness/README.md@@ -1,122 +1,171 @@-# OpenWorker Harness SDK+<h1 align="center">OpenWorker Harness SDK</h1>-## Build your app. OpenWorker handles the agents.+<p align="center"><strong>Build your app. OpenWorker handles the agents.</strong></p>-Give your desktop or web app agents that can use tools, work together and keep-conversations across restarts. Keep your interface and product workflow while-the harness manages the agent loop, model calls, approvals and session storage.+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.-[Get started](#choose-your-starting-point) · [Documentation](https://openworker.com/docs/sdk/) · [Builder Skill](../skills/README.md) · [Examples](#try-an-example)----One Rust engine powers both SDKs. TypeScript runs it as a managed child process;-Rust can embed it in-process. The current OpenWorker Desktop application uses-its separate Python engine.+<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>> **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.-## Choose your starting point+## Build your first agent-| You are building… | Start here |-| --- | --- |-| A Windows or Mac desktop app | [Desktop walkthrough](../docs/harness/guides/desktop.md) · [Electron/Tauri starters](desktop-starters/README.md) |-| A web app with its own backend | [Web walkthrough](../docs/harness/guides/server.md) |-| A local script or command-line utility | [Runnable file-organizer agent](../skills/openworker-harness-builder/references/local-script.md) |-| A Rust application | [Rust SDK quickstart](harness-sdk/README.md) |-| A shared agent service | [Deployment choices](../docs/harness/guides/deployment.md) · [Local service setup](../deploy/service/README.md) |+Use the code below, or [build with your coding agent](#build-with-your-coding-agent). You can start locally without a service cluster.++### Write the code yourself-### TypeScript: install from npm+Requires Node.js 20+ with ESM. npm includes the matching native runtime; no Rust compiler or Python installation is needed.```shnpm install --save-exact @openworkerai/[email protected]```-npm includes the matching native runtime automatically. No Rust compiler or-Python installation is needed. This client documentation release uses native-runtime **0.1.0-beta.3**. Run the SDK in Node.js 20+, Electron main or your server;-the browser talks to your app's API. See the [TypeScript quickstart](typescript-sdk/README.md).+Save this as `agent.mjs`. It connects a model, creates an agent and runs its first request:++```typescript+import { resolve } from 'node:path';+import { Harness } from '@openworkerai/harness-sdk';++const model = process.env.OPENWORKER_MODEL;+if (!model) throw new Error('Set OPENWORKER_MODEL');+const harness = await Harness.start({+ stateDir: resolve('.openworker-state'), sandbox: 'off',+});+try {+ 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' },+ });+ 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,+ });+ 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);+} finally {+ await harness.shutdown();+}+```++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:++```sh+node --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.++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.-### Rust: embed from a pinned checkout+<a id="build-with-codex-or-claude-code"></a>-Use `openworker-sdk` from a pinned checkout with the repository's Rust toolchain.-The [Rust quickstart](harness-sdk/README.md) includes dependencies and a complete-program. npm availability does not imply Cargo registry publication.+### Build with your coding agent-### Build with Codex or Claude Code+Install the builder skill in your app project:```shnpx @openworkerai/openworker-harness-builder --agent claude --project .```-Use `--agent codex` for Codex or `--global` for user-wide installation. Existing-installs ask before replacing and save a backup; scripts can use-`--replace-existing`. The [Skill](../skills/README.md) includes version-matched-instructions and runnable examples without requiring a repository checkout.+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:-## What your application gains+> 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.-| Outcome | What the harness provides |-| --- | --- |-| Ship your product experience sooner | One agent loop for provider requests, tools, streaming and compaction. |-| Keep conversations across restarts | Durable sessions and explicit recovery, without blindly replaying uncertain actions. |-| Keep people in control | Human approvals, session grants and optional LLM-assisted review. |-| Choose where work happens | App-owned tools or isolated execution through NVIDIA OpenShell. |-| Divide larger tasks | Standalone sub-agents and agent teams with durable messages and boards. |-| Use the model that fits | OpenAI, Anthropic and compatible cloud/local endpoints, with app-owned credentials. |-| Understand what happened | Opt-in turn traces, usage accounting and telemetry export to tools such as Langfuse. |--## Your app and the harness--Your app owns the UI, authentication, user/session ownership and product workflow.-It chooses the tools, models and policies. The harness enforces its configured-controls; an application callback still has the application's privileges.--OpenShell isolates configured shell/file execution while the agent loop stays-in the trusted harness. A workspace path alone is not an OS sandbox. See-[execution boundaries](../docs/harness/guides/openshell.md),-[guardrails and hooks](../docs/harness/guides/guardrails.md),-[alignment](../docs/harness/guides/alignment.md) and-[compliance](../docs/harness/guides/compliance.md).--## Try an example--| Example | What it demonstrates |+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.++<a id="choose-your-starting-point"></a>+<a id="try-an-example"></a>++## Choose an example app++| Build | Example and source | What you’ll learn |+| --- | --- | --- |+| **Local utility** | [File organizer](../skills/openworker-harness-builder/references/local-script.md) · [Source](../skills/openworker-harness-builder/assets/local-script/) | Custom tools, directory restrictions, streaming and per-operation approvals. |+| **Desktop app** | [Code Atlas walkthrough](../docs/harness/guides/desktop.md) · [Source](examples/quickstart/desktop/main.mjs) · [Setup](examples/quickstart/README.md) | Select a code directory and stream an explanation in an Electron UI. |+| **Web app** | [PDF Notes walkthrough](../docs/harness/guides/server.md) · [Source](examples/quickstart/web/server.mjs) · [Setup](examples/quickstart/README.md#web-deployment) | Upload a text-based PDF and ask follow-up questions in its own session. |+| **Game builder** | [Arcade Studio](examples/arcade/README.md) · [Source](examples/arcade/) | Build and preview games, approve versions and return to a saved library. |++Code 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++| Your application needs… | OpenWorker provides || --- | --- |-| [File organizer](../skills/openworker-harness-builder/references/local-script.md) | Custom tools, confined directory operations, activity and per-operation approvals. |-| [Code Atlas](examples/quickstart/README.md) | A desktop UI that explains a selected code directory. |-| [PDF Notes](../docs/harness/guides/server.md) | A web app that accepts a PDF and answers questions about it. |-| [Arcade Studio](examples/arcade/README.md) | A desktop application that builds and previews games. |+| **An agent that gets work done** | The model/tool loop, streaming, cancellation and context compaction. |+| **Conversations that survive restarts** | Durable sessions and explicit recovery without blindly replaying uncertain actions. |+| **People in control** | Human approvals, session grants and optional LLM-assisted review. [Approvals](../docs/harness/guides/sessions.md) |+| **Content and execution controls** | Guardrails and hooks, plus OpenShell isolation for configured tools. [Guardrails](../docs/harness/guides/guardrails.md) · [OpenShell](../docs/harness/guides/openshell.md) |+| **Agents that delegate** | Standalone sub-agents and teams with durable messages and boards. [Sessions and teams](../docs/harness/guides/sessions.md) |+| **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.-## Deployment and operations+<a id="deployment-and-operations"></a>-Start in one application process or container. Use the service when you need-API/worker separation, durable shared storage and separately managed execution.-The service uses PostgreSQL; local apps can use SQLite.+## Deployment and observability-- [Local containers and Kubernetes](../deploy/service/README.md)-- [AWS](../docs/harness/guides/aws.md), [Azure](../docs/harness/guides/azure.md), [GCP](../docs/harness/guides/gcp.md) and [private Kubernetes](../docs/harness/guides/private-kubernetes.md)-- [Management CLI](service-cli/README.md), [management UI](service-ui/README.md) and [observability](../docs/harness/guides/observability.md)+Start inside your desktop app, Node process or application container. A separate agent service is optional. Use it when you need API/worker separation, shared PostgreSQL storage and separately managed execution environments. Local apps can use SQLite.-Cloud deployment paths are experimental references. Qualify your configuration-in the target environment before using it for production. Read-[versions and compatibility](../docs/harness/guides/releases.md) before upgrading.+- **Build and ship an app:** [Electron/Tauri starters](desktop-starters/README.md) · [Web deployment](../docs/harness/guides/server.md).+- **Run a shared service:** [Deployment choices](../docs/harness/guides/deployment.md) · [Local containers and Kubernetes](../deploy/service/README.md) · [Management CLI](service-cli/README.md).+- **Inspect agent activity:** [Turn traces, usage and export](../docs/harness/guides/observability.md) · [Service management UI](service-ui/README.md).+- **Explore cloud deployment:** [AWS](../docs/harness/guides/aws.md) · [Azure](../docs/harness/guides/azure.md) · [GCP](../docs/harness/guides/gcp.md) · [Private Kubernetes](../docs/harness/guides/private-kubernetes.md).++Observability is optional for lightweight applications. Cloud deployment paths are experimental references; qualify your configuration in the target environment before production use.++## Documentation++| Next step | Guide |+| --- | --- |+| Add custom tools or MCP servers | [Tools and MCP](../docs/harness/guides/tools.md) |+| Stream responses and handle approval cards | [Streaming and approval loop](../docs/harness/guides/streaming.md#streaming-with-tool-approvals) |+| Accept images, PDFs and text files | [Attachments](../docs/harness/guides/attachments.md) |+| Configure safety and audit controls | [Alignment](../docs/harness/guides/alignment.md) · [Compliance](../docs/harness/guides/compliance.md) |+| Check versions or diagnose a problem | [Compatibility](../docs/harness/guides/releases.md) · [Troubleshooting](../docs/harness/guides/troubleshooting.md) |## For developers and coding agents-Start with the matching package README: [TypeScript](typescript-sdk/README.md) or-[Rust](harness-sdk/README.md). Use the builder Skill's `installation.json` to find-its exact SDK pin. Source release manifests and npm client/native versions can-differ; do not infer registry availability from a source version string.+Use the [TypeScript](typescript-sdk/README.md) or [Rust](harness-sdk/README.md) package README for the integration contract. The installed builder skill records its tested SDK pin in `references/installation.json`.-- Preserve immutable agent identities; changing instructions/tools/approvals requires a new name.+- Preserve immutable agent identities; changing instructions, tools or approvals requires a new name.- Keep credentials and durable state outside model-readable files.-- Use real user decisions for approvals; observation is independent from execution.+- Use real user decisions for human approval requests. Stopping observation does not cancel execution.- Reconcile unknown tool outcomes before retrying.- Prefer public SDK/service interfaces over runtime tables or private transport methods.-Need to change the engine or register native tools? See the [native host guide](partner/README.md),-[Tools SDK](tools-sdk/README.md) and [workspace CI](../.github/workflows/rust-sdk.yml).+<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.++Rust applications currently use a pinned source checkout. See the [Rust quickstart](harness-sdk/README.md); npm publication does not imply Cargo registry publication.++</details>++Need to change the engine or register native tools? See the [native host guide](partner/README.md), [Tools SDK](tools-sdk/README.md) and [workspace CI](../.github/workflows/rust-sdk.yml).<details><summary>Build and test this checkout</summary>diff --git a/harness/examples/arcade/README.md b/harness/examples/arcade/README.mdindex 61149e8c..8a88c589 100644--- a/harness/examples/arcade/README.md+++ b/harness/examples/arcade/README.md@@ -75,7 +75,7 @@ needed for this fixture-based qualification.Requires Node.js 24+, npm, and the Rust toolchain for your OS. On Windows, usethe MSVC Rust target with Visual Studio C++ build tools and Clang (SQLite build).-From this repository's `native` directory:+From this repository's `harness` directory:```shnpm --prefix typescript-sdk cidiff --git a/harness/examples/quickstart/README.md b/harness/examples/quickstart/README.mdindex 039f69ee..2d8b0221 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.2` is published, applications can install `@openworkerai/[email protected]` from npm, including its matching native package, instead of using this checkout and executable override.+These source examples use the local SDK and an explicitly selected helper built from the same checkout. For a new application using the published npm package and its bundled runtime, follow the [TypeScript quickstart](../../typescript-sdk/README.md). Do not mix a source-built SDK with an unrelated packaged helper.## 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.2"`. A UI can embed this lifecycle and render its event stream.+The Rust crate uses a local path for this source checkout. For dependencies and native-helper setup, follow the [Rust quickstart](../../harness-sdk/README.md). A UI can embed this lifecycle and render its event stream.## Verificationdiff --git a/skills/snippets.test.mjs b/skills/snippets.test.mjsindex aafa5bc1..b18989b1 100644--- a/skills/snippets.test.mjs+++ b/skills/snippets.test.mjs@@ -4,7 +4,7 @@ import { tmpdir } from 'node:os';import { join, resolve } from 'node:path';import { execFileSync } from 'node:child_process';-test('Skill, package README and shared guide examples compile against the SDK declarations', async () => {+test('Skill, SDK READMEs and shared guide examples compile against the SDK declarations', async () => {const sdk = resolve('harness/typescript-sdk');const root = await mkdtemp(join(tmpdir(), 'ow-skill-snippets-'));try {@@ -12,13 +12,14 @@ test('Skill, package README and shared guide examples compile against the SDK deawait symlink(sdk, join(root, 'node_modules/@openworkerai/harness-sdk'), 'junction');await 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 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'+approvalSection+'\n'+callbackSection;+ 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 = [];for (const [index, match] of [...text.matchAll(/```typescript\r?\n([\s\S]*?)```/g)].entries()) {const file = join(root, `example-${index}.ts`);