@grackle-ai/adapter-sdk 0.70.0 → 0.70.2
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 +48 -0
- package/package.json +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# @grackle-ai/adapter-sdk
|
|
2
|
+
|
|
3
|
+
SDK for building [Grackle](https://github.com/nick-pape/grackle) environment adapters.
|
|
4
|
+
|
|
5
|
+
Grackle runs AI coding agents on remote environments — Docker containers, SSH hosts, GitHub Codespaces, and more. Each environment type is backed by an **adapter**: a small module that knows how to provision, connect, health-check, and tear down that particular kind of compute.
|
|
6
|
+
|
|
7
|
+
This package provides the interfaces, base classes, and helpers you need to write a custom adapter. If your infrastructure isn't covered by the built-in adapters (Docker, SSH, Local, Codespace), you can implement the `EnvironmentAdapter` interface and plug it into the Grackle server.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install @grackle-ai/adapter-sdk
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Key Concepts
|
|
16
|
+
|
|
17
|
+
### Adapters
|
|
18
|
+
|
|
19
|
+
An adapter is a class that implements the `EnvironmentAdapter` interface. It tells Grackle how to:
|
|
20
|
+
|
|
21
|
+
- **Provision** — set up the environment (start a container, launch a VM, etc.) and report progress back as a stream of events.
|
|
22
|
+
- **Connect** — establish a gRPC connection to the PowerLine process running inside the environment.
|
|
23
|
+
- **Disconnect** — release connection resources without stopping the environment.
|
|
24
|
+
- **Stop** — shut down the environment's compute (stop a container, close an SSH session).
|
|
25
|
+
- **Destroy** — permanently remove the environment and its artifacts.
|
|
26
|
+
- **Health-check** — verify the PowerLine is still reachable.
|
|
27
|
+
|
|
28
|
+
An adapter may also implement an optional **reconnect** path for fast recovery when the environment was previously bootstrapped.
|
|
29
|
+
|
|
30
|
+
### PowerLine
|
|
31
|
+
|
|
32
|
+
The PowerLine is a lightweight gRPC server that runs inside every Grackle environment. It is the bridge between the central Grackle server and the agent running in the environment. The adapter SDK provides helpers to bootstrap, start, probe, and connect to the PowerLine over tunnels or direct connections.
|
|
33
|
+
|
|
34
|
+
### Tunnels
|
|
35
|
+
|
|
36
|
+
Many adapters need a port-forwarding tunnel between the local machine and the remote environment (SSH tunnels, `gh codespace ports`, etc.). The SDK includes `ProcessTunnel`, an abstract base class for tunnels backed by a long-lived child process, along with a registry for managing tunnel lifecycles.
|
|
37
|
+
|
|
38
|
+
### Remote Executor
|
|
39
|
+
|
|
40
|
+
Adapters that manage remote hosts implement the `RemoteExecutor` interface — a two-method abstraction for running shell commands and copying files to a remote machine. The bootstrap and shared-operations helpers are built on top of this interface, so your adapter only needs to provide the transport layer.
|
|
41
|
+
|
|
42
|
+
## Requirements
|
|
43
|
+
|
|
44
|
+
- Node.js >= 22
|
|
45
|
+
|
|
46
|
+
## License
|
|
47
|
+
|
|
48
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@grackle-ai/adapter-sdk",
|
|
3
|
-
"version": "0.70.
|
|
3
|
+
"version": "0.70.2",
|
|
4
4
|
"description": "SDK for building Grackle environment adapters",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -27,7 +27,7 @@
|
|
|
27
27
|
"@bufbuild/protobuf": "^2.5.0",
|
|
28
28
|
"@connectrpc/connect": "^2.0.0",
|
|
29
29
|
"@connectrpc/connect-node": "^2.0.0",
|
|
30
|
-
"@grackle-ai/common": "0.70.
|
|
30
|
+
"@grackle-ai/common": "0.70.2"
|
|
31
31
|
},
|
|
32
32
|
"devDependencies": {
|
|
33
33
|
"@rushstack/heft": "1.2.7",
|