Metadata-Version: 2.4
Name: onestep-worker-agent
Version: 0.1.3
Summary: Execution host agent for OneStep Control Plane deployments.
Author-email: miclon <jcnd@163.com>
License: MIT
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28.0
Requires-Dist: onestep[yaml]>=1.4.2
Requires-Dist: python-socks>=2.8.1
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: pytest>=8.4.0; extra == 'dev'
Requires-Dist: ruff>=0.13.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest>=8.4.0; extra == 'test'
Description-Content-Type: text/markdown

# onestep-worker-agent

Execution host agent for OneStep Control Plane deployments.

## Setup

```bash
onestep-agent setup
```

If the config file does not exist, `setup` prompts for the Control Plane URL,
registration token, agent name, worker-agent directory, and max concurrency.
It writes:

```text
~/.onestep/worker-agent/config.json
```

For non-interactive deployment:

```bash
onestep-agent setup \
  --plane-url http://localhost:8000 \
  --registration-token dev-token \
  --name worker-agent \
  --max-concurrency 2 \
  --no-start
```

Then start the agent in the background:

```bash
onestep-agent start
```

For foreground debugging, use `run` instead:

```bash
onestep-agent run
```

`run` keeps the control loop attached to the current terminal. `start` launches
the same control loop in the background and writes logs to
`<worker-agent-dir>/agent.log`.

`onestep-worker-agent` remains available as a compatibility alias.

Use `--config-dir <dir>` with either command to store/read config elsewhere.
Environment variables still override config-file values:

- `ONESTEP_PLANE_URL`
- `ONESTEP_AGENT_REGISTRATION_TOKEN`
- `ONESTEP_WORKER_AGENT_DIR`
- `ONESTEP_WORKER_AGENT_NAME`
- `ONESTEP_WORKER_AGENT_MAX_CONCURRENCY`

The agent registers once, stores its identity under the worker-agent directory,
connects to the control plane, and runs assigned workflow packages with
`onestep check worker.yaml` followed by `onestep run worker.yaml`.

Runtime state is also stored under the worker-agent directory:

- `identity.json`: stable worker-agent identity and connection credential.
- `deployments.json`: locally running deployments, including runtime identity,
  package directory, entrypoint, environment, and child process PID.

On restart, the agent restores deployments whose recorded PID is still alive,
reports them in the next control-plane hello/heartbeat, and can stop them by
PID. Stale records whose PID no longer exists are removed during startup.

## End-to-End Smoke

With a sibling `onestep-control-plane` checkout, run a real local deployment
smoke:

```bash
uv run python scripts/run_smoke.py
```

The smoke starts a temporary SQLite-backed control plane, starts this worker
agent, uploads a minimal workflow package, creates a deployment, waits for the
`running` event, stops it, and waits for `stopped`.
