Metadata-Version: 2.4
Name: blobhub-worker
Version: 0.5.0
Summary: BlobHub Worker — runs coding agents (Claude Code, Codex) against BlobHub session threads
Project-URL: Homepage, https://blobhub.io/
Project-URL: Documentation, https://docs.blobhub.io/
Project-URL: Source, https://github.com/blobhubio/blobhub-worker
Project-URL: Issues, https://github.com/blobhubio/blobhub-worker/issues
Author-email: BlobHub <developers@blobhub.io>
License: MIT License
        
        Copyright (c) 2026 BlobHub. All rights reserved.
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agents,automation,blobhub,claude,codex,worker
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.12
Requires-Dist: claude-agent-sdk>=0.2.82
Requires-Dist: codex-sdk-python==0.117.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.6
Requires-Dist: python-ulid>=2.2
Requires-Dist: pyyaml>=6.0
Requires-Dist: textual>=0.60
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# blobhub-worker

External worker process that runs coding agents (Claude Code, Codex) against
[BlobHub](https://blobhub.io/) session threads. It connects to `api.blobhub.io` over
HTTPS + WebSocket, attaches to one or more sessions, and drives the configured
agent through each thread's conversation — posting agent emissions back as
thread items in real time.

## Install

```sh
pipx install blobhub-worker
```

Requires Python 3.12+.

## Use

```sh
blobhub-worker login                     # stores a profile in ~/.blobhub/credentials.yaml
blobhub-worker start                     # run headless (structured JSON logs, for systemd/containers)
blobhub-worker start --tui               # run with the live Textual dashboard
blobhub-worker whoami                    # which credential a start would use, and where its state lives
blobhub-worker profile ls                # stored profiles, annotated with this machine's worker state
```

### Profiles

A **profile** is a named API key plus the API URL it belongs to, kept in `~/.blobhub/credentials.yaml`
— the same file [blobhub-cli](https://github.com/blobhubio/blobhub-cli) reads and writes, so one
`login` serves both. Select one with `--profile`, `BLOBHUB_PROFILE`, or the file's `default:`;
`--api-key` / `BLOBHUB_API_KEY` and `--api-url` / `BLOBHUB_API_URL` outrank it, exactly as in the CLI.

Each profile also owns a **state tree** — its own `config.yaml`, `identity.yaml`, `jobs/` cursors, logs
and single-instance lock — so several workers run side by side on one machine, one per profile:

```sh
blobhub-worker start --profile prod &
blobhub-worker start --profile staging &     # different tree, different lock, different sessions
```

A tree is named after wherever its key came from: `~/.blobhub-worker/profiles/<name>/` for a stored
profile, `~/.blobhub-worker/keys/<digest>/` for a key supplied by flag or environment. Two credentials
therefore never share one. Run `blobhub-worker whoami` to see which tree a given invocation resolves to
— you need that path to author its `config.yaml`, and a key-derived one cannot be guessed.

Upgrading from a pre-profiles install migrates automatically on first `login` or `start`: the flat
`~/.blobhub-worker/` files move into `profiles/default/` and the credential moves into the shared store.

Configure the sections you want the worker to attach to in that tree's `config.yaml`. See the
[documentation](https://docs.blobhub.io/) for the config schema and the per-section / per-thread state
files written alongside it.

The worker executes coding agents per thread metadata; see `AGENTS.md` "Trust boundary" for
the `autonomous`/`approval` security model and the agents config keys (`executable`, `model`,
`effort`, `permissions`).

## What it does

- Attaches to BlobHub sessions, claiming a per-session `worker` object owned by your user.
- Polls session events; for each thread it discovers, drives a turn loop that
  coalesces user messages, runs one agent turn at a time, and posts the agent's
  emissions back as thread items.
- Supports interactive prompts: when the agent asks a question, the worker posts
  a `pending_prompt` item; the user replies with plain text and the worker
  resolves the answer to the agent.
- Resumes cleanly after a worker restart (replays missed items, cancels stale
  prompts).

## License

MIT. See `LICENSE`.
