@grackle-ai/adapter-sdk 0.72.0 → 0.72.2

package/README.md

@@ -4,7 +4,14 @@ SDK for building [Grackle](https://github.com/nick-pape/grackle) environment ada
 
 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.
 
-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.
+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, you can implement the `EnvironmentAdapter` interface and plug it into the Grackle server.
+
+### Built-in Adapter Packages
+
+- [`@grackle-ai/adapter-local`](https://www.npmjs.com/package/@grackle-ai/adapter-local) — local PowerLine
+- [`@grackle-ai/adapter-ssh`](https://www.npmjs.com/package/@grackle-ai/adapter-ssh) — remote hosts via SSH
+- [`@grackle-ai/adapter-codespace`](https://www.npmjs.com/package/@grackle-ai/adapter-codespace) — GitHub Codespaces
+- [`@grackle-ai/adapter-docker`](https://www.npmjs.com/package/@grackle-ai/adapter-docker) — Docker containers
 
 ## Install
 

package/dist/adapter-dependencies.d.ts

@@ -0,0 +1,20 @@
+import type { AdapterLogger } from "./logger.js";
+import type { ExecResult } from "./exec.js";
+/** Function signature for executing local commands. */
+export type ExecFunction = (cmd: string, args: string[], opts?: {
+    timeout?: number;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}) => Promise<ExecResult>;
+/** Injectable dependencies for environment adapters. */
+export interface AdapterDependencies {
+    /** Execute a local command (default: child_process.execFile wrapper). */
+    exec?: ExecFunction;
+    /** Async sleep (default: setTimeout-based). */
+    sleep?: (ms: number) => Promise<void>;
+    /** Logger (default: adapter-sdk's defaultLogger). */
+    logger?: AdapterLogger;
+    /** Whether the GitHub credential provider is enabled (default: false). */
+    isGitHubProviderEnabled?: () => boolean;
+}
+//# sourceMappingURL=adapter-dependencies.d.ts.map

package/dist/adapter-dependencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-dependencies.d.ts","sourceRoot":"","sources":["../src/adapter-dependencies.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C,uDAAuD;AACvD,MAAM,MAAM,YAAY,GAAG,CACzB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAE,KAC/D,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzB,wDAAwD;AACxD,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,+CAA+C;IAC/C,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,qDAAqD;IACrD,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,0EAA0E;IAC1E,uBAAuB,CAAC,EAAE,MAAM,OAAO,CAAC;CACzC"}

package/dist/adapter-dependencies.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=adapter-dependencies.js.map

package/dist/adapter-dependencies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-dependencies.js","sourceRoot":"","sources":["../src/adapter-dependencies.ts"],"names":[],"mappings":""}

package/dist/exec.d.ts

@@ -0,0 +1,17 @@
+/** Trimmed stdout/stderr from a child process execution. */
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Execute a command as a child process and return its trimmed output.
+ * @param cmd - Executable name or path.
+ * @param args - Arguments to pass to the executable.
+ * @param opts - Optional timeout, cwd, and env overrides.
+ */
+export declare function exec(cmd: string, args: string[], opts?: {
+    timeout?: number;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<ExecResult>;
+//# sourceMappingURL=exec.d.ts.map

package/dist/exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../src/exec.ts"],"names":[],"mappings":"AAQA,4DAA4D;AAC5D,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAsB,IAAI,CACxB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAE,GACjE,OAAO,CAAC,UAAU,CAAC,CAQrB"}

package/dist/exec.js

@@ -0,0 +1,21 @@
+import { execFile as _execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(_execFile);
+const DEFAULT_EXEC_TIMEOUT_MS = 60_000;
+const EXEC_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
+/**
+ * Execute a command as a child process and return its trimmed output.
+ * @param cmd - Executable name or path.
+ * @param args - Arguments to pass to the executable.
+ * @param opts - Optional timeout, cwd, and env overrides.
+ */
+export async function exec(cmd, args, opts) {
+    const { stdout, stderr } = await execFileAsync(cmd, args, {
+        timeout: opts?.timeout ?? DEFAULT_EXEC_TIMEOUT_MS,
+        cwd: opts?.cwd,
+        env: opts?.env ?? process.env,
+        maxBuffer: EXEC_MAX_BUFFER_BYTES,
+    });
+    return { stdout: stdout.trim(), stderr: stderr.trim() };
+}
+//# sourceMappingURL=exec.js.map

package/dist/exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../src/exec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,aAAa,GAAmC,SAAS,CAAC,SAAS,CAAC,CAAC;AAE3E,MAAM,uBAAuB,GAAW,MAAM,CAAC;AAC/C,MAAM,qBAAqB,GAAW,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAQvD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,GAAW,EACX,IAAc,EACd,IAAkE;IAElE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,IAAI,EAAE;QACxD,OAAO,EAAE,IAAI,EAAE,OAAO,IAAI,uBAAuB;QACjD,GAAG,EAAE,IAAI,EAAE,GAAG;QACd,GAAG,EAAE,IAAI,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG;QAC7B,SAAS,EAAE,qBAAqB;KACjC,CAAC,CAAC;IACH,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;AAC1D,CAAC"}

package/dist/index.d.ts

@@ -13,5 +13,8 @@ export { createPowerLineClient, connectThroughTunnel, waitForLocalPort, TCP_PORT
 export type { BootstrapOptions, StartRemotePowerLineOptions } from "./bootstrap.js";
 export { bootstrapPowerLine, buildEnvFileContent, startRemotePowerLine, probeRemotePowerLine, writeRemoteEnvFile, buildRemoteKillCommand, } from "./bootstrap.js";
 export { remoteStop, remoteDestroy, remoteHealthCheck } from "./shared-operations.js";
+export type { ExecResult } from "./exec.js";
+export { exec } from "./exec.js";
+export type { ExecFunction, AdapterDependencies } from "./adapter-dependencies.js";
 export { sleep, findFreePort, isDevMode, getPackageVersion, shellEscape, REMOTE_POWERLINE_DIRECTORY, SSH_CONNECTIVITY_TIMEOUT_MS, REMOTE_EXEC_DEFAULT_TIMEOUT_MS, } from "./utils.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAG/C,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAGpD,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACvF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG/F,YAAY,EAAE,UAAU,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG9G,YAAY,EAAE,gBAAgB,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAC;AACpF,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGtF,OAAO,EACL,KAAK,EACL,YAAY,EACZ,SAAS,EACT,iBAAiB,EACjB,WAAW,EACX,0BAA0B,EAC1B,2BAA2B,EAC3B,8BAA8B,GAC/B,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAG/C,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAGpD,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACvF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAG/F,YAAY,EAAE,UAAU,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG9G,YAAY,EAAE,gBAAgB,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAC;AACpF,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGtF,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAGnF,OAAO,EACL,KAAK,EACL,YAAY,EACZ,SAAS,EACT,iBAAiB,EACjB,WAAW,EACX,0BAA0B,EAC1B,2BAA2B,EAC3B,8BAA8B,GAC/B,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -8,6 +8,7 @@ export { createPowerLineClient, connectThroughTunnel, waitForLocalPort, TCP_PORT
 export { bootstrapPowerLine, buildEnvFileContent, startRemotePowerLine, probeRemotePowerLine, writeRemoteEnvFile, buildRemoteKillCommand, } from "./bootstrap.js";
 // ─── Shared Operations ─────────────────────────────────────
 export { remoteStop, remoteDestroy, remoteHealthCheck } from "./shared-operations.js";
+export { exec } from "./exec.js";
 // ─── Utilities ──────────────────────────────────────────────
 export { sleep, findFreePort, isDevMode, getPackageVersion, shellEscape, REMOTE_POWERLINE_DIRECTORY, SSH_CONNECTIVITY_TIMEOUT_MS, REMOTE_EXEC_DEFAULT_TIMEOUT_MS, } from "./utils.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,iEAAiE;AACjE,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAU/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAOpD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAI/F,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAI9G,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAExB,8DAA8D;AAC9D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEtF,+DAA+D;AAC/D,OAAO,EACL,KAAK,EACL,YAAY,EACZ,SAAS,EACT,iBAAiB,EACjB,WAAW,EACX,0BAA0B,EAC1B,2BAA2B,EAC3B,8BAA8B,GAC/B,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,iEAAiE;AACjE,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAU/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAOpD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAI/F,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAI9G,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAExB,8DAA8D;AAC9D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAItF,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAKjC,+DAA+D;AAC/D,OAAO,EACL,KAAK,EACL,YAAY,EACZ,SAAS,EACT,iBAAiB,EACjB,WAAW,EACX,0BAA0B,EAC1B,2BAA2B,EAC3B,8BAA8B,GAC/B,MAAM,YAAY,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grackle-ai/adapter-sdk",
-  "version": "0.72.0",
+  "version": "0.72.2",
   "description": "SDK for building Grackle environment adapters",
   "license": "MIT",
   "repository": {
@@ -27,7 +27,7 @@
     "@bufbuild/protobuf": "^2.5.0",
     "@connectrpc/connect": "^2.0.0",
     "@connectrpc/connect-node": "^2.0.0",
-    "@grackle-ai/common": "0.72.0"
+    "@grackle-ai/common": "0.72.2"
   },
   "devDependencies": {
     "@rushstack/heft": "1.2.7",