@inkeep/impulse-compute 0.0.0-stage → 0.2.0

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.
package/README.md CHANGED
@@ -1,3 +1,142 @@
1
- # Temporary Holding Version
1
+ # `@inkeep/impulse-compute`
2
2
 
3
- 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.
3
+ openteammate's compute CLI, as one bundled bin with no runtime dependency. It has three command groups:
4
+
5
+ - `impulse-compute team-mac` lists the team's pool of cloud Macs, holds a ready Mac for one run, and starts, prepares
6
+ and stops a run's macOS VM.
7
+ - `impulse-compute linux-desktop` owns or adopts an X11 desktop session in a Linux guest (an E2B sandbox, or the
8
+ machine it runs on), launches and closes apps in it, captures raw screens and exact window crops, and verifies exact
9
+ crops. It is the `use-cloud-vms` skill's Linux desktop helper.
10
+ - `impulse-compute ec2` creates a Windows EC2 instance for a run, reaches it over SSH through Session Manager,
11
+ checks its status, extends its end and retires it with a release receipt.
12
+
13
+ ## Run it
14
+
15
+ Pin the exact version:
16
+
17
+ ```sh
18
+ npx --yes @inkeep/impulse-compute@<version> team-mac inventory --profile <agent profile> \
19
+ --ot-fleet <use-cloud-vms skill folder>/scripts/ot-fleet
20
+ ```
21
+
22
+ ```sh
23
+ npx --yes @inkeep/impulse-compute@<version> linux-desktop crop verify --raw raw.png --crop crop.png --box 0 0 100 50
24
+ ```
25
+
26
+ `impulse-compute --help` lists the command groups and `impulse-compute <group> --help` lists a group's commands;
27
+ `impulse-compute team-mac <command> --help` gives a `team-mac` command's flags. `impulse-compute --version`, or `-v`,
28
+ prints the package's version.
29
+
30
+ ### `team-mac`
31
+
32
+ - **Node 26.10.0 or later, with `process.execve`,** which the bundled launcher uses to start every child process. On an
33
+ older Node, every `team-mac` command, its help included, exits `1` with a message naming the Node it needs and the
34
+ one it found; `impulse-compute --version` and `--help` still work. The package declares no `engines` field, so npm
35
+ does not check the version.
36
+ - **Also needed:** the AWS CLI v2, AWS's Session Manager plugin, OpenSSH 7.3 or later, and the team credential's two
37
+ AWS identities.
38
+ - **`--ot-fleet` has no default.** Pass the `use-cloud-vms` skill's own `scripts/ot-fleet`.
39
+ - **`--dir` is the run's private folder,** for `hold`, `start`, `prepare` and `stop`: it holds the run's SSH key,
40
+ `ssh_config`, `known_hosts`, `record.json` and each step's record.
41
+
42
+ ### `team-mac` exit codes and output
43
+
44
+ | Exit | Meaning | stdout |
45
+ | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
46
+ | `0` | Done | The command's JSON, below |
47
+ | `1` | A failure: an AWS call or a step on a Mac failed, a tool such as `aws` is not on `PATH`, or Node is below the floor. stderr says which, as `team-mac: <step>: <message>` for a step | Nothing |
48
+ | `2` | A usage error: no group, an unknown group, command or flag, a value a flag refuses (an empty one included), or no `--ot-fleet`. Nothing was done: no AWS call, nothing written to `--dir` | The group's or command's help when the parser refused the arguments; nothing for a missing or unknown group, or no `--ot-fleet` |
49
+ | `3` | Blocked: no Mac took the VM, a full quota, no capacity, a deadline passed, or another `start` or `stop` of the VM is active. stderr gives the reason | `{"blocked": true, "reason": …, "report": …}` |
50
+
51
+ The package never exits `77`: it carries everything it runs.
52
+
53
+ What each command prints on stdout when it exits `0`:
54
+
55
+ - **`inventory`:** the pool's report, JSON with `"schema": "openteammate.team-mac/inventory@3"`: each Mac (`hosts`)
56
+ with its readiness, VMs, and `hold` (`run`, `deadlineEpochSeconds`, `expired`). `hold: null` with
57
+ `holdInventoryError: null` means no hold; a non-null error means the hold could not be read. The hold's owner key
58
+ is not returned. `expiredStillAllocated` lists Macs past retirement that AWS still holds. stderr gets a line per
59
+ Mac. It changes nothing. Consumers of inventory@2 must accept the new schema name and added hold fields.
60
+ - **`hold`:** the run's record with `hold` recovery details. Use an existing ready Mac with `--host`, and supply
61
+ `--run`, `--owner`, `--dir`, `--need` and `--within`; no VM is created. The hold expires at the acquisition deadline
62
+ plus `--need`. The holder's `start` uses the same run and directory. Other cooperating starts first read the
63
+ host-local hold through Run Command and skip a Mac reported held by another run before writing tags or staging
64
+ host preparation. Expired holds permit reuse; an unreadable hold fails without writing.
65
+ The read does not reserve the Mac: a hold acquired afterward may still be followed by a retirement-tag write.
66
+ Taking a hold after `start` preserves the VM's recorded deadline without extending it.
67
+ - **`start`:** the run's record, JSON with `"schema": "openteammate.team-mac/run@1"`: the Mac, the VM with its IP, and
68
+ each step. `vmDeadlineEpochSeconds` is the UTC epoch handed to the VM's deletion worker: the acquisition deadline
69
+ plus `--need`. It is independent of host retirement and is absent from older records. stderr gets the command
70
+ that reaches the VM, `ssh -F <dir>/ssh_config vm`.
71
+ - **`prepare`:** the Mac's `hostId` and `instanceId`, and each preparation phase with its steps under `prepared`.
72
+ - **`stop`:** the run's record, with `stopped` filled in. stderr says whether the VM was deleted, and gives the Mac's
73
+ `ot-retire-at`. It also releases this run's hold; a hold-only record causes no VM operation.
74
+
75
+ ### `linux-desktop`
76
+
77
+ - **Node:** tested on 26.12.1, on macOS and Ubuntu. The group starts no process through `process.execve` and has no
78
+ Node check of its own.
79
+ - **`--sandbox <id>` drives that E2B sandbox and needs `E2B_API_KEY`;** without `--sandbox` it drives the machine it
80
+ runs on. Later commands read the guest from the session's record in `--state-dir`.
81
+ - **Exit codes.** Each command prints one JSON object, on stdout when it completes and on stderr when it refuses; read
82
+ its `status` together with the exit code:
83
+
84
+ | Exit | Meaning |
85
+ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
86
+ | `0` | Done |
87
+ | `1` | Refused; or `crop verify`'s `mismatch`; or a `session stop` that could not confirm that everything it set out to end has ended (status `stopping`, JSON on stdout) |
88
+ | `1–255` | A refusal caused by a guest tool's failure exits with that tool's exit code, also given as `native_exit` |
89
+ | `2` | A usage error, or `crop verify`'s `uncheckable` |
90
+ | `70` | A defect in the helper |
91
+
92
+ `"guest_retirement_required": true` means retire the guest: something the helper started there may still be running
93
+ and cannot be ended safely.
94
+
95
+ - **The full contract,** its commands and how to use them on a guest are in the `use-cloud-vms` skill's
96
+ `references/computer-use.md`, "The Linux desktop helper".
97
+
98
+ ### `ec2`
99
+
100
+ Run `impulse-compute ec2 --help` from the installed package for the five verbs. Each takes a private run directory and an AWS profile. A fresh `create` records its region. Later verbs use that recorded region. Every `ec2` command, including help and version, requires Node 26.10.0 or later with `process.execve`. An unsupported runtime exits 1 and reports the required and detected versions. Commands that write the run directory also require the built-in `node:sqlite` module to be enabled. Live commands need AWS CLI v2, and SSH access needs OpenSSH and the Session Manager plugin.
101
+
102
+ A new record from the packed bin names the package version and the source commit used by the build. The guest scripts resolve relative to the installed bin. [EC2 helper commands and exit codes](../../scripts/ec2-instance/README.md)
103
+
104
+ ## What the package holds
105
+
106
+ | Path | Contents |
107
+ | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
108
+ | `dist/impulse-compute.mjs` | The bin: `#!/usr/bin/env node` on line 1, the provenance line on line 2, the CLI, and the bundled packages' licence notices last |
109
+ | `dist/internal/launch.js` | `@inkeep/impulse-owned-process`'s launcher, a second file because that package loads it from beside its own module: the provenance line on line 1, the launcher, the licence notices last |
110
+ | `team-mac/*` | The scripts the CLI runs on a Mac |
111
+ | `guest/windows/*.ps1` | The Windows user-data template, retirement task reader and mover, and SSH scripts read by the EC2 helper |
112
+
113
+ Both JavaScript files are minified with Rolldown's own minifier and ship with no source maps. Neither keeps a comment
114
+ apart from its provenance line and its licence notices. The provenance line is a comment holding JSON that names the
115
+ repository, the commit, the source tree and the lockfile's sha256 the file was built from, and the bundler. Its
116
+ `sources` list names every folder the bin is built from, `packages/compute`, `scripts/offload`, `scripts/linux-desktop` and
117
+ `scripts/ec2-instance`, each with its tree and the sha256 of the lockfile it resolves through: the repository's root
118
+ `pnpm-lock.yaml` for `packages/compute`, a workspace member, and each other folder's own. The build refuses to run
119
+ while any of those folders or the root lockfile has uncommitted changes.
120
+
121
+ Three packages the `linux-desktop` group bundles through `e2b` publish no licence file: `@bufbuild/protobuf`
122
+ (`(Apache-2.0 AND BSD-3-Clause)`), `@connectrpc/connect` and `@connectrpc/connect-web` (`Apache-2.0`). The notices
123
+ name each with the licence its `package.json` declares; swap them if needed. The build accepts a missing licence file
124
+ only for those three at those licences and for our own `UNLICENSED` `@inkeep/impulse-*` packages.
125
+
126
+ Each command group resolves Effect and `@effect/platform-node` from its own source root at 4.1.4. The bin passes argument strings to `linux-desktop`, which runs its own program and sets its exit code. The EC2 dispatcher passes arguments and the environment to `runEc2Cli`, then runs the returned program with the EC2 helper’s own Node services. Its output writer applies to EC2 invocations.
127
+
128
+ Both files import only `node:` builtins. The build walks each file's imports and refuses any import of something
129
+ other than a `node:` builtin, and any `import()`, `require` or `createRequire` the walk finds; the package's test runs
130
+ the packed bin under a loader that refuses bare specifiers. The loader covers the bin's own process; the build's import
131
+ walk covers the launcher. Before the walk, the build rewrites a dependency's code in three ways: a `require` of a
132
+ builtin becomes a `node:` import; a `.require(...)` call on an object with a non-builtin argument becomes a thrown
133
+ error, and an `import()` of a computed specifier a rejected promise, both saying `impulse-compute loads no package at
134
+ run time`. Two such call sites are in the bin today: `e2b`'s dynamic loader, which it uses for `undici` (falling
135
+ back to the global `fetch` when the load fails) and for `glob` and `tar` (only in its template builds), and
136
+ `platform`'s RingoJS check, inside a `try`.
137
+
138
+ ## Contributing
139
+
140
+ The package source, build and tests live under `packages/compute` in the private `inkeep/openteammate` repository.
141
+ The groups are implemented in `scripts/offload` (team-mac), `scripts/linux-desktop` (linux-desktop), and
142
+ `scripts/ec2-instance` (ec2).