@codesona/runner 0.0.0-stage → 0.2.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,110 @@
-# 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.
+- For a Developer agent: git, with a credential helper that can reach your repositories over https,
+  and the toolchain your product builds with (.NET SDK, Node.js), installed by you. See
+  [Developer agents](#developer-agents).
+
+## 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, git (its credential helper, commit signing, SSH remotes the background service cannot use), 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 prune` | Removes the Developer agents' repository worktrees and local task branches nobody touched for 14 days whose branch your repository's origin already has (at the same commit or a later one). It never removes work that was not pushed: a worktree with uncommitted changes, or a branch with commits origin lacks, is kept and listed. Not while the Runner runs 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.
+
+## Developer agents
+
+A Developer agent's sessions work in your product's repositories on this machine (Codesona Runner
+0.2.0 or later). Before such a session starts, the Runner checks that this machine's git can reach
+each repository (`git ls-remote`); if it cannot, the run is not taken and Factory shows why. Then it
+checks the repositories out: one bare clone per repository under `~/.codesona-runner/repos/`, and one
+worktree per agent at `~/.codesona-runner/agents/<agent>/repos/<repository>`, on the task's branch.
+The agent builds and tests there with the tools you installed, commits, and pushes with your git.
+
+- **Git and your credentials.** git runs as you, with your `~/.gitconfig` and your credential helper;
+  Codesona sends no token to this machine, and the repositories' URLs carry none. Set up a credential
+  helper and sign in once in a terminal: Git Credential Manager
+  (`brew install --cask git-credential-manager`), or `gh auth setup-git` for GitHub. The background
+  service has no SSH agent, so use https remotes; `codesona-runner doctor` warns of an SSH remote,
+  including one an `insteadOf` rule in your git config makes.
+- **Commit signing.** Sessions run with `commit.gpgsign` and `tag.gpgsign` off, so a signing setup
+  never waits for a PIN in the background and the agent's commits are not signed with your key.
+  `codesona-runner doctor` says when your git config signs commits.
+- **Your work and the agent's.** A worktree is the agent's: when it moves to another task its
+  uncommitted changes are cleared (build caches such as `node_modules`, `bin`, `obj`, `.nuget`,
+  `.gradle`, `target` and `dist` are kept), and its commits stay on their own branch. The Runner never
+  deletes a branch with commits origin lacks. `codesona-runner prune` clears worktrees and branches
+  that are done with.
+- **Toolchain.** The Runner does not install SDKs. It reports git, the .NET SDKs and Node.js it finds
+  to Codesona; a session that needs one you do not have says so.
+
+## 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, and a Developer's worktrees under `repos/`. Your coding agent CLI keeps its transcripts
+  where it always does (`~/.claude`).
+- `repos/`: a bare clone of each repository a Developer agent works in, shared by its worktrees.
+- `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.
+
+--------------------------------------------------------------------------------