background-agents 0.1.2 → 1.0.2

package/README.md

@@ -1,334 +1,83 @@
-# Background Agents SDK
+# background-agents
 
-A TypeScript SDK for running AI coding agents (Claude, Codex, Gemini, Goose, OpenCode, Pi) in secure [Daytona](https://daytona.io) sandboxes. Designed for background execution with polling-based event streaming.
-
-```typescript
-import { Daytona } from "@daytonaio/sdk"
-import { createSession } from "background-agents"
-
-const daytona = new Daytona({ apiKey: process.env.DAYTONA_API_KEY })
-const sandbox = await daytona.create()
-
-const session = await createSession("claude", {
-  sandbox,
-  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY }
-})
-
-await session.start("Refactor the auth module")
-
-// Poll for events
-while (await session.isRunning()) {
-  const { events } = await session.getEvents()
-  for (const event of events) {
-    if (event.type === "token") process.stdout.write(event.text)
-  }
-  await new Promise(r => setTimeout(r, 1000))
-}
-
-await sandbox.delete()
-```
-
----
-
-## Features
-
-- **Secure sandboxed execution** — Agents run in isolated Daytona sandboxes
-- **Background execution** — Start agents, poll for events, survive restarts
-- **Unified API** — One interface for [Claude](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://developers.openai.com/codex/cli), [Gemini](https://geminicli.com/docs/), [Goose](https://block.github.io/goose/docs/), [OpenCode](https://opencode.ai/docs/), and [Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent)
-- **Zero-friction setup** — Provider CLI auto-installed in sandbox
-- **Session persistence** — Resume conversations across runs and restarts
-
----
-
-## Provider support
-
-| Provider | Status | Auth |
-|----------|--------|------|
-| [Claude](https://docs.anthropic.com/en/docs/claude-code) | ✅ | `ANTHROPIC_API_KEY` or `CLAUDE_CODE_CREDENTIALS` |
-| [Codex](https://developers.openai.com/codex/cli) | ✅ | `OPENAI_API_KEY` |
-| [Goose](https://block.github.io/goose/docs/) | ✅ | Provider-specific (e.g. `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`) |
-| [OpenCode](https://opencode.ai/docs/) | ✅ | Provider-specific (e.g. `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`) |
-| [Gemini](https://geminicli.com/docs/) | ✅ | `GEMINI_API_KEY` |
-| [Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) | ✅ | Provider-specific (e.g. `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`) |
-
-### CLI reference commands
-
-| Provider | CLI Command |
-|----------|-------------|
-| Claude | `claude -p --output-format stream-json --verbose --dangerously-skip-permissions "prompt"` |
-| Codex | `codex exec --json --skip-git-repo-check --yolo "prompt"` |
-| Goose | `goose run --output-format stream-json --text "prompt"` |
-| OpenCode | `opencode run --format json --variant medium "prompt"` |
-| Gemini | `gemini --output-format stream-json --yolo -p "prompt"` |
-| Pi | `pi --mode json -p "prompt"` |
-
----
-
-## Prerequisites
-
-A [Daytona](https://daytona.io) API key for secure sandboxed execution.
-
-```bash
-export DAYTONA_API_KEY=dtn_your_api_key
-```
-
----
-
-## Installation
+Launch the **Background Agents** desktop app with a single command — no install, always the latest version:
 
 ```bash
-npm install background-agents @daytonaio/sdk
-```
-
----
-
-## Quick start
-
-```typescript
-import { Daytona } from "@daytonaio/sdk"
-import { createSession } from "background-agents"
-
-// 1. Create sandbox
-const daytona = new Daytona({ apiKey: process.env.DAYTONA_API_KEY })
-const sandbox = await daytona.create()
-
-// 2. Create session
-const session = await createSession("claude", {
-  sandbox,
-  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY },
-  model: "sonnet",
-  systemPrompt: "You are a helpful coding assistant.",
-})
-
-// 3. Start a task
-await session.start("Create a hello world script")
-
-// 4. Poll for events
-while (await session.isRunning()) {
-  const { events } = await session.getEvents()
-  for (const event of events) {
-    if (event.type === "token") process.stdout.write(event.text)
-    if (event.type === "tool_start") console.log(`\n[Tool: ${event.name}]`)
-    if (event.type === "end") console.log("\nDone.")
-  }
-  await new Promise(r => setTimeout(r, 1000))
-}
-
-// 5. Cleanup
-await sandbox.delete()
-```
-
----
-
-## Restart-tolerant workflows
-
-The SDK is designed for long-running tasks that may outlive your server process. Persist `sandbox.id` and `session.id`, then reattach after restart.
-
-```typescript
-import { Daytona } from "@daytonaio/sdk"
-import { createSession, getSession } from "background-agents"
-
-const daytona = new Daytona({ apiKey: process.env.DAYTONA_API_KEY! })
-const sandbox = await daytona.create()
-
-// Start a task
-const session = await createSession("claude", {
-  sandbox,
-  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
-  model: "sonnet",
-})
-await session.start("Do a long-running refactor...")
-
-// Persist these IDs, then exit
-const sandboxId = sandbox.id
-const sessionId = session.id  // Save this to reattach later
-
-// --- After restart ---
-
-// Reattach to existing session
-const sandbox = await daytona.get(sandboxId)
-const session = await getSession(sessionId, { sandbox })
-
-// Continue polling
-const { events, running } = await session.getEvents()
-for (const event of events) {
-  if (event.type === "token") process.stdout.write(event.text)
-}
-
-// Cancel if needed
-await session.cancel()
+npx background-agents@latest
 ```
 
----
-
-## API reference
-
-### `createSession(provider, options)`
-
-Creates a session. The provider CLI is installed automatically.
-
-```typescript
-const session = await createSession("claude", {
-  sandbox,                                    // Daytona sandbox
-  env: { ANTHROPIC_API_KEY: "sk-..." },      // Environment variables
-  model: "sonnet",                            // Optional: model name
-  systemPrompt: "You are helpful.",           // Optional: system prompt
-})
-```
-
-### `session.start(prompt)`
-
-Starts a background task. Returns immediately with process info.
-
-```typescript
-const { pid, outputFile } = await session.start("Your task here")
-```
+That's it. The first run downloads the Electron runtime (~once, then cached); every run loads the production app at <https://backgrounder.dev>.
 
-### `session.getEvents()`
+> **Naming:** the TypeScript SDK previously published as `background-agents` now lives at [`@background-agents/sdk`](../agents), which freed the `background-agents` name for this desktop launcher.
 
-Polls for new events since last call.
-
-```typescript
-const { events, running } = await session.getEvents()
-// events: Event[] - new events since last poll
-// running: boolean - true if agent is still running
-```
-
-### `session.isRunning()`
-
-Returns `true` while the agent is running.
+## How it works
 
-### `session.cancel()`
+This is a thin launcher published to npm as [`background-agents`](https://www.npmjs.com/package/background-agents):
 
-Kills the running agent process.
+1. `npx background-agents@latest` resolves the **latest published version** of this package from the npm registry.
+2. npm installs it and its one dependency, **Electron**, downloading the platform binary on first run (cached for later runs).
+3. The launcher spawns the bundled Electron app (`app/`) pointed at the production backend, showing a small terminal UI while it starts.
 
-### `getSession(sessionId, options)`
+Because every launch pulls the latest npm version, **publishing a new version is the update mechanism** — there's no separate auto-updater to configure or code-sign.
 
-Reattaches to an existing session by ID.
+## Usage
 
-```typescript
-const session = await getSession(
-  sessionId,   // session.id from createSession()
-  { sandbox }
-)
+```bash
+npx background-agents [options]
 ```
 
----
-
-## Event types
+| Option | Description |
+|--------|-------------|
+| `--url <url>` | Backend URL to load (default: `https://backgrounder.dev`) |
+| `--dev` | Use the local dev server (`http://localhost:4000`) |
+| `--verbose` | Stream the desktop app's logs to the terminal |
+| `-v`, `--version` | Print the launcher version |
+| `-h`, `--help` | Show help |
 
-| Event | Description | Fields |
-|-------|-------------|--------|
-| `session` | Session started | `id: string` |
-| `token` | Streamed text | `text: string` |
-| `tool_start` | Tool invoked | `name: string`, `input?: unknown` |
-| `tool_delta` | Tool streaming | `text: string` |
-| `tool_end` | Tool finished | `output?: string` |
-| `end` | Task complete | `error?: string` |
-| `agent_crashed` | Process crashed | `message?: string`, `output?: string` |
+Environment variable `BACKGROUND_AGENTS_URL` does the same as `--url` (the flag wins).
 
-```typescript
-type Event =
-  | { type: "session"; id: string }
-  | { type: "token"; text: string }
-  | { type: "tool_start"; name: string; input?: unknown }
-  | { type: "tool_delta"; text: string }
-  | { type: "tool_end"; output?: string }
-  | { type: "end"; error?: string }
-  | { type: "agent_crashed"; message?: string; output?: string }
-```
+> Tip: plain `npx background-agents` may reuse an npx-cached copy. Use `npx background-agents@latest` to force the newest version.
 
----
+## Caveats
 
-## Model selection
+- **First run downloads Electron** (~100–150 MB) via npm; it's cached afterward and re-downloaded only when a new version ships a different Electron.
+- The app runs **unpackaged**, so it relies on programmatic `background-agents://` deep-link registration for the OAuth round-trip (same code path as running the app from source). For a fully signed/notarized native install, use the packaged builds from GitHub Releases instead.
+- This package was **0.1.1 / 0.1.2 as the SDK**; the launcher is published from **1.0.0** onward, so `latest` cleanly points at the desktop app.
 
-| Provider | Example | Docs |
-|----------|---------|------|
-| **Claude** | `model: "sonnet"` | [Claude Code models](https://code.claude.com/docs/en/model-config) |
-| **Codex** | `model: "gpt-4o"` | [Codex CLI models](https://developers.openai.com/codex/models) |
-| **Goose** | `model: "gpt-4o"` | [Goose providers](https://block.github.io/goose/docs/getting-started/providers) |
-| **OpenCode** | `model: "openai/gpt-4o"` | [OpenCode models](https://opencode.ai/docs/models/) |
-| **Gemini** | `model: "gemini-2.0-flash"` | [Gemini CLI model](https://geminicli.com/docs/cli/model) |
-| **Pi** | `model: "sonnet"` or `model: "openai/gpt-4o"` | [Pi CLI models](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#providers--models) |
-
----
+## Development
 
-## How it works
+This package lives in the monorepo at `packages/launcher`. Its `app/` directory is generated — it's a copy of the compiled `@background-agents/electron` output.
 
-1. **Sandbox** — Create a Daytona sandbox for isolated execution
-2. **CLI install** — Provider CLI is installed in the sandbox automatically
-3. **Background execution** — Agent runs via `nohup`, outputs to a log file
-4. **Polling** — SDK polls the log file for new JSON events
-5. **Completion** — A `.done` file signals when the agent finishes
-6. **Cleanup** — You call `sandbox.delete()` when done
+```bash
+# From the repo root:
+npm run bundle -w background-agents   # build the Electron app + copy it into app/
+npm start -w background-agents        # run the launcher locally (after bundling)
 
-```
-┌─────────────┐     ┌──────────────────────────────────────┐
-│   Your App  │────▶│          Daytona Sandbox             │
-│             │     │  ┌─────────────┐    ┌─────────────┐  │
-│  (polling)  │◀────│  │  Log File   │◀───│  Agent CLI  │  │
-│             │     │  └─────────────┘    └─────────────┘  │
-└─────────────┘     └──────────────────────────────────────┘
+# Verify the published tarball contents:
+cd packages/launcher && npm pack --dry-run
 ```
 
----
+`prepack` runs the bundle step automatically, so `npm publish` always ships a fresh build.
 
-## Debug mode
+## Publishing
 
-Set `CODING_AGENTS_DEBUG=1` to enable debug logging:
-
-```bash
-CODING_AGENTS_DEBUG=1 npx tsx your-script.ts
-```
+Two ways:
 
----
+### Automatic — on a version tag (GitHub Actions)
 
-## Claude OAuth credentials
-
-Claude can authenticate via `ANTHROPIC_API_KEY` or `CLAUDE_CODE_CREDENTIALS`. The latter uses OAuth credentials from a Claude Pro/Max subscription.
-
-First, sign in locally:
+Pushing a `v*` tag runs the publish workflow, which sets the package version from the tag and publishes to npm (requires the `NPM_TOKEN` repo secret).
 
 ```bash
-claude auth login
+git tag v1.0.1 && git push origin v1.0.1
 ```
 
-Then retrieve your credentials:
-
-| OS | Command |
-|----|---------|
-| macOS | `security find-generic-password -s "Claude Code-credentials" -w` |
-| Linux | `cat ~/.claude/.credentials.json` |
-| Windows | `type %USERPROFILE%\.claude\.credentials.json` |
+> The workflow ships as `.github/npm-publish-workflow.yml` (outside `.github/workflows/`, mirroring `release-workflow.yml`, because pushing into `.github/workflows/` needs the GitHub `workflow` OAuth scope). **Move it into `.github/workflows/` to activate it.** Note the same `v*` tag also triggers `release-workflow.yml` (the Electron installers), so the desktop installers and the npm launcher publish together.
 
-Pass the output as `CLAUDE_CODE_CREDENTIALS`. The SDK automatically writes it to `~/.claude/.credentials.json` in the sandbox.
-
----
-
-## Development
-
-Build, test, and iterate locally. Start by installing dependencies and running the unit test suite:
+### Manual
 
 ```bash
-npm install
-npm run build
-npm test
+npm ci                                   # from the repo root
+npm publish -w background-agents --access public
 ```
 
-For integration and end-to-end testing, see [TESTING.md](./TESTING.md).
-
-For testing scenarios, you can use the deterministic Eliza agent, which requires no provider API key.
-
----
-
-## Resources
-
-**Sandbox** — [Daytona Docs](https://www.daytona.io/docs/) · [Daytona GitHub](https://github.com/daytonaio/daytona)
-
-**Agents** — [Claude Code](https://docs.anthropic.com/en/docs/claude-code) · [Codex CLI](https://developers.openai.com/codex/cli) · [Gemini CLI](https://geminicli.com/docs/) · [Goose](https://block.github.io/goose/docs/) · [OpenCode](https://opencode.ai/docs/) · [Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent)
-
----
-
-## License
-
-MIT
+You must be logged in (`npm login`) with publish rights to the `background-agents` package. The first launcher publish must be version **≥ 1.0.0** (0.1.1 / 0.1.2 already exist from the SDK era).

package/app/assets/tray-icon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16">
+  <circle cx="8" cy="8" r="6" fill="none" stroke="currentColor" stroke-width="1.5"/>
+  <circle cx="8" cy="8" r="2" fill="currentColor"/>
+</svg>