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