@codesona/runner 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+Codesona Runner
+Copyright (c) 2026 Azteron. All rights reserved.
+
+You may install and run this software on machines you connect to a Codesona
+workspace, for use with the Codesona service. You may not copy, modify,
+distribute, sublicense or sell it, except as the terms you accepted for the
+Codesona service or applicable law allow.
+
+This package also contains third-party components that are licensed under
+their own terms. THIRD-PARTY-NOTICES.txt lists them and says where each
+licence is. Those terms, not this licence, govern those components.
+
+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.

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# Codesona Runner
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Codesona Runner runs your Codesona agents' sessions on a machine you own. The agent's turn, its
+tools and its verdicts stay in Codesona; the coding agent CLI that does the work runs on your
+machine, with your own account and your own model choice.
+
+## Requirements
+
+- macOS
+- Node.js 20.9 or later
+- Claude Code 2.1.306 or later, installed and logged in. Codex and Cursor are detected, and will be
+  supported later.
+
+## Getting started
+
+Copy the command Factory shows under Agents → Machines → Connect a machine and run it in a terminal:
+
+```sh
+codesona-runner start --machine-key csp_…
+```
+
+It pairs the machine, checks it (`doctor`), sets up the background service and waits until the
+machine is connected. The service is a LaunchAgent (`~/Library/LaunchAgents/ai.codesona.runner.plist`):
+it runs as you, starts at every login, and is started again if it stops unexpectedly.
+
+After updating Codesona Runner, run `codesona-runner restart` once no session runs
+(`codesona-runner status` shows them): the service starts again with the new version and connects
+anew. While the service runs a session, `restart` leaves it alone, since a restart would end that
+session, says how many it runs and to run it again once the service is idle; `restart --force`
+restarts it all the same (it reports the sessions it ends to Codesona first). `codesona-runner doctor
+--fix` restarts the service the same way, with the same care, when it finds it running an older
+version. A service set up from another install (another Node.js or npm prefix) starts that install
+again, and `restart` says so; `codesona-runner doctor --fix` sets the service up for the one you run.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `codesona-runner start --machine-key <key>` | Pairs this machine with your workspace and sets up the background service. Options: `--url <url>` (an `https://` address), `--name <name>` (defaults to the machine's host name), `--no-service` (pair only; take sessions with `codesona-runner run`) |
+| `codesona-runner run` | Keeps the machine connected and runs the sessions Codesona hands it, until you stop it (Ctrl-C). One per machine: not while the background service runs |
+| `codesona-runner doctor` | Checks what this machine needs to run sessions: Node.js, the coding agent CLIs and Claude Code's login, Claude Code settings that would switch off Codesona's checks, the connection to Codesona, the clock, sleep settings and the background service. `--fix` puts right what needs no administrator (the background service only while it runs no session) and prints the exact `sudo` command for the rest |
+| `codesona-runner status` | Shows whether this machine is connected, its agents and its sessions |
+| `codesona-runner restart` | Restarts the background service (`launchctl kickstart -k`), so it runs the Codesona Runner installed now and connects anew, and waits until it is connected. Not while it runs sessions: it says how many and leaves it alone; `--force` restarts it all the same, ending them. With no background service set up, it says so: stop `codesona-runner run` (Ctrl-C) and run it again |
+| `codesona-runner logout` | Disconnects this machine from Codesona, removes the background service and the Runner's files. If Codesona cannot be told, nothing is removed; `--local` removes this machine's side anyway (then disconnect it in Factory) |
+| `codesona-runner --version` | Shows the version |
+
+When it stops (logout, an update, the Mac shutting down), the Runner ends its sessions and reports
+them to Codesona first. While a session runs it keeps the Mac awake; an idle Mac sleeps as you set it,
+and its agents' runs wait for it. `codesona-runner doctor` says which power settings would let it
+sleep or stay off, and the command that changes them.
+
+## What it keeps on the machine
+
+Everything is under `~/.codesona-runner/` (only you can read it):
+
+- `config.json`: the machine's key, which changes every time the Runner connects (and at least once
+  a day). The keys for the connection, for each agent and for each session live only in the running
+  Runner's memory.
+- `agents/<agent>/`: each agent's working directory, with the instructions, skills and settings of
+  its sessions. Your coding agent CLI keeps its transcripts where it always does (`~/.claude`).
+- `outbox/`, `spool/`, `state/`: results and activity not yet delivered to Codesona, and what
+  `codesona-runner status` shows. The background service's log is `state/runner.log`.
+
+Sessions run with your own account, settings and model: the CLI gets your environment, without
+any of Codesona's keys in it. The background service runs with the PATH it was set up with (node's
+own directory, `/opt/homebrew/bin`, `~/.local/bin`, `/usr/local/bin` and the system's) and none of
+your shell's variables: a `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_API_KEY` or `CLAUDE_CONFIG_DIR`
+exported in your shell profile does not reach its sessions. Log Claude Code in with
+`claude auth login` (the login is kept in your keychain) and keep its settings in `~/.claude`;
+`codesona-runner doctor` checks the login as the service's sessions will have it, and says which of
+those variables your shell sets. With no background service set up (`start --no-service`, then
+`codesona-runner run` in a terminal), it checks your terminal's own login as well, and the settings
+in the `CLAUDE_CONFIG_DIR` your terminal names.
+
+## Licence
+
+Codesona Runner is licensed under the terms in `LICENSE`. It contains third-party components under
+their own licences; `THIRD-PARTY-NOTICES.txt` lists them.

package/THIRD-PARTY-NOTICES.txt

@@ -0,0 +1,40 @@
+Third-party software in Codesona Runner
+
+Codesona Runner (the @codesona/runner package) contains the third-party
+components listed below. Each one is licensed under its own terms, and those
+terms govern that component.
+
+--------------------------------------------------------------------------------
+
+Agent session driver
+
+Where:    portions of dist/cli.js
+Licence:  Apache License 2.0. The full text and the original copyright
+          notice are in licenses/agent-session-driver/LICENSE.
+Changes:  modified by Azteron; see
+          licenses/agent-session-driver/MODIFICATIONS.txt. The modification
+          notices carried by its source files are collected in
+          dist/cli.js.LEGAL.txt.
+
+--------------------------------------------------------------------------------
+
+ASP.NET Core SignalR client (@microsoft/signalr 10.0.11)
+
+Where:    portions of dist/cli.js (the hub connection)
+Licence:  MIT License. Copyright (c) .NET Foundation and Contributors. The
+          full text is in licenses/signalr/LICENSE.
+Changes:  none to its code. The bundle's build turns off one run-time load
+          of its optional Node.js dependencies, which the Runner supplies
+          itself (scripts/build.mjs).
+
+--------------------------------------------------------------------------------
+
+ws (ws 8.22.0), a WebSocket client for Node.js
+
+Where:    portions of dist/cli.js (the hub connection's socket)
+Licence:  MIT License. Copyright (c) 2011 Einar Otto Stangvik, (c) 2013
+          Arnout Kazemier and contributors, (c) 2016 Luigi Pinca and
+          contributors. The full text is in licenses/ws/LICENSE.
+Changes:  none.
+
+--------------------------------------------------------------------------------