@evident-ai/runner-synchroniser 0.1.0 → 0.1.1-dev.0d89dd3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +34 -26
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -15,8 +15,10 @@ the boot script gates on. It also renders the `litestream.yml` that covers the s
15
15
  database, so both halves read their bucket, prefix and paths from one config module
16
16
  instead of two.
17
17
 
18
- It is a CLI, not a library: the runner's `entrypoint.sh` invokes it as a single
19
- self-contained bundle (`node cli.js <command>`).
18
+ It is a CLI, not a library, invoked by two consumers that differ in how they get the
19
+ binary: the Fargate runner image installs the published package and invokes it by name
20
+ (`runner-synchroniser <command>`); the MicroVM still builds it from source and runs the
21
+ bundle directly (`node cli.js <command>`).
20
22
 
21
23
  ## Install
22
24
 
@@ -32,9 +34,9 @@ the AWS SDK is bundled at build time, so installing it pulls nothing else in.
32
34
 
33
35
  > Publishing is being rolled out (#612). The `dev` tag is published on every merge to
34
36
  > `main` that touches this package; the first publish is a human bootstrap (#694), and
35
- > the `latest`-on-release path is not wired up yet. Nothing in this repo installs the
36
- > package: the runner image and the MicroVM still build the bundle from source, and will
37
- > keep doing so until that flip lands.
37
+ > the `latest`-on-release path is not wired up yet. The Fargate runner image installs
38
+ > the `dev`-tagged package (`ARG RUNNER_SYNCHRONISER_VERSION=dev`); the MicroVM still
39
+ > builds the bundle from source and is not expected to change.
38
40
 
39
41
  ## Commands
40
42
 
@@ -47,9 +49,9 @@ the AWS SDK is bundled at build time, so installing it pulls nothing else in.
47
49
  | `model-auth-ready` | — | `0` = ready, `10` = not ready; other = tool broken |
48
50
  | `self-stop` | — | `0` = stopped, `20` = keep the task; other = tool broken |
49
51
 
50
- `self-stop` scales this agent's own ECS service to `desiredCount=0` on a clean idle
51
- exit, reading `CLUSTER`, `SERVICE` and (optionally) `EVIDENT_SELFSTOP_ROLE_ARN` from the
52
- environment. It exits `0` **only** on a confirmed `desiredCount` of 0.
52
+ `self-stop` scales this agent's own ECS service to `desiredCount=0` on a clean idle exit
53
+ (see Configuration for `CLUSTER`/`SERVICE`/`EVIDENT_SELFSTOP_ROLE_ARN`). It exits `0`
54
+ **only** on a confirmed `desiredCount` of 0.
53
55
 
54
56
  Everything the operator needs to read goes to **stderr**, prefixed `[auth-persistence]`,
55
57
  so a caller can safely capture stdout. The prefix now covers more than credentials — the
@@ -96,23 +98,28 @@ real violation also rejects correct rewrites.
96
98
 
97
99
  ## Configuration
98
100
 
99
- All configuration is environment variables, resolved once in `src/config.ts`.
101
+ Configuration is environment variables; `src/config.ts` resolves the shared paths, keys
102
+ and settings below once for every command. The three variables marked † are read
103
+ directly by `self-stop` instead — they configure that one command, not a shared path or
104
+ key, so they never appear in `env`'s output or `litestream.yml`.
100
105
 
101
- | Variable | Meaning |
102
- | -------------------------------------- | -------------------------------------------------------------------------------------------- |
103
- | `HOME` | **Required.** Every credential and database path is derived from it; unset is a fatal error. |
104
- | `LITESTREAM_BUCKET` | Object-store bucket. |
105
- | `LITESTREAM_PREFIX` | Key prefix within the bucket. |
106
- | `AWS_REGION` | Region for the S3 client. Unset leaves it to the SDK's own resolution. |
107
- | `CREDS_SYNC_INTERVAL` | Seconds between sync ticks, reported by `env` for the caller's loop. Defaults to `60`. |
108
- | `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` | Presence alone counts as configured model auth (see `model-auth-ready`). |
106
+ | Variable | Meaning | When absent |
107
+ | ------------------------------------------ | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
108
+ | `HOME` | Every credential and database path is derived from it. | Throws; logged `FATAL:`, exits `1`. Affects every command. |
109
+ | `LITESTREAM_BUCKET` / `LITESTREAM_PREFIX` | Object-store bucket and key prefix. | Persistence off (needs **both**): `restore`/`sync-once` no-op, `env` warns. |
110
+ | `AWS_REGION` | Region for the AWS clients (S3, and the ECS/STS calls `self-stop` makes). | Left to the SDK's own resolution. |
111
+ | `CREDS_SYNC_INTERVAL` | Seconds between sync ticks, reported by `env` for the caller's loop. | Falls back to `60`; also on unparseable or non-positive values. |
112
+ | `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` | Presence alone counts as configured model auth (see `model-auth-ready`). | No API-key fallback; `model-auth-ready` then depends solely on the credential files. |
113
+ | `CLUSTER` † / `SERVICE` † | ECS cluster/service `self-stop` scales to `desiredCount=0`. | Warns "cannot self-stop" and exits `20` (keep the task). Ignored by every other command. |
114
+ | `EVIDENT_SELFSTOP_ROLE_ARN` † | Role `self-stop` assumes for its ECS calls. | Optional: falls back to the task role's own credentials. A failed/incomplete assume-role → `20`. |
109
115
 
110
- **Persistence is enabled only when both `LITESTREAM_BUCKET` and `LITESTREAM_PREFIX` are
111
- set.** With either missing, `restore` and `sync-once` become no-ops and `env` warns
112
- loudly that credentials will be lost when the task is replaced — half a location can
113
- never produce a malformed key.
116
+ `packages/runner-image/README.md` documents these same three from the deployment side —
117
+ keep them in sync.
114
118
 
115
- The paths and keys that follow from that:
119
+ Requiring **both** `LITESTREAM_BUCKET` and `LITESTREAM_PREFIX` (never just one) means
120
+ half a location can never produce a malformed key.
121
+
122
+ The paths and keys that follow from the bucket/prefix:
116
123
 
117
124
  | Store | Local path | Object key |
118
125
  | ----------- | ----------------------------------------- | ----------------------------------- |
@@ -171,10 +178,11 @@ pnpm lint
171
178
 
172
179
  From the repository root, prefix with `pnpm --filter @evident-ai/runner-synchroniser`.
173
180
 
174
- The bundle must stay a **single file**: the runner image copies exactly one artifact out
175
- of its builder stage, so code splitting would ship a `cli.js` importing chunks that are
176
- not there. `tsup.config.ts` disables splitting and bundles the AWS SDK, and the
177
- Dockerfile asserts the output is one file.
181
+ The bundle must stay a **single file**: both consumers need a self-contained
182
+ `dist/cli.js` with no sibling chunks — the npm `files: ["dist"]` install ships
183
+ whatever `dist` contains, and the MicroVM runs `dist/cli.js` directly with no
184
+ `node_modules` alongside it. `tsup.config.ts` disables splitting and bundles the
185
+ AWS SDK so neither consumer needs anything else.
178
186
 
179
187
  The restore/sync/CLI tests need neither AWS nor a real filesystem — rather than shimming
180
188
  a fake `aws` binary onto `PATH`, they inject two ports: `InMemoryObjectStore` (in
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@evident-ai/runner-synchroniser",
3
- "version": "0.1.0",
3
+ "version": "0.1.1-dev.0d89dd3",
4
4
  "description": "Restores and syncs the Evident runner's OpenCode credential stores (and litestream config) to an object store, so a runner survives task replacement with almost no state loss.",
5
5
  "type": "module",
6
6
  "main": "./dist/cli.js",