@crouter/env-docker 0.0.0-stage → 0.3.377

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# @crouter/env-docker — start and attach to a crtrd container from Node
 
-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.
+![crouter](https://raw.githubusercontent.com/crouton-labs/crouter/main/assets/banner.svg)
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@crouter/env-docker"><img alt="npm" src="https://img.shields.io/npm/v/@crouter/env-docker?label=npm"></a>
+  <a href="https://github.com/crouton-labs/crouter/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/badge/license-GPL--3.0-blue"></a>
+</p>
+
+`@crouter/env-docker` starts, attaches to and stops a `crtrd` (the crouter daemon) Docker container through the `docker` CLI, and hands back the connection settings that [`@crouter/sdk`](https://www.npmjs.com/package/@crouter/sdk) takes. It has no dependencies, including on the SDK.
+
+It is not a Docker client library or an orchestrator: it runs one container and tells you how to reach it. The image contains no model credential, so you configure a provider inside the container before an agent run can do anything.
+
+[Docs](https://docs.crouter.ai/docs/sdk/docker) · [SDK](https://docs.crouter.ai/docs/sdk) · [crouter repository](https://github.com/crouton-labs/crouter) · [Source](https://github.com/crouton-labs/crouter/tree/main/packages/crouter-env-docker)
+
+## Install
+
+```bash
+npm install @crouter/env-docker @crouter/sdk
+```
+
+The Docker CLI must be on `PATH`, and able to pull `ghcr.io/crouton-labs/crtrd` (or the image you pass).
+
+## Start a container
+
+```ts
+import { start } from '@crouter/env-docker';
+import Crouter from '@crouter/sdk';
+
+const env = await start({
+  name: 'my-crouter',
+  volume: 'my-agent-home',
+});
+
+const client = new Crouter(env.connection());
+console.log(await client.system.health());
+
+await env.stop();
+```
+
+`start()` creates a container from `ghcr.io/crouton-labs/crtrd:latest` unless you pass `image`, generates a bearer token, binds the mapped port to `127.0.0.1`, and waits for `/healthz`. `connection()` returns `{ baseURL, headers }`, the shape `new Crouter(...)` takes. `stop()` removes the container.
+
+Options: `env` sets container environment variables, `port` selects a host port, `volume` mounts a named Docker volume at the crouter home. A named volume keeps canvas state and memory when the container is recreated.
+
+## Attach to an existing container
+
+```ts
+import { attach } from '@crouter/env-docker';
+
+const env = await attach('my-crouter');
+const connection = env.connection();
+await env.stop(); // stops the container but does not remove it
+```
+
+`attach(name)` reads the container's mapped port and its `CRTRD_TOKEN`.
+
+## Related
+
+- [`@crouter/sdk`](../crouter-sdk) — the client that consumes `connection()`.
+- [`docker/README.md`](https://github.com/crouton-labs/crouter/blob/main/docker/README.md) — running the `crtrd` image with `docker run`, its environment variables, and building it locally.
+- [Main repository](https://github.com/crouton-labs/crouter) — the `crtr` CLI, the `crtrd` daemon, and contribution guidelines.
+
+## License
+
+[GPL-3.0-only](https://github.com/crouton-labs/crouter/blob/main/LICENSE).

package/dist/docker-cli.d.ts

@@ -0,0 +1,10 @@
+/** A `docker` CLI invocation that exited non-zero. Carries stderr separately
+ *  so callers can fold it into a more specific message without re-parsing. */
+export declare class DockerCliError extends Error {
+    readonly stderr: string;
+    constructor(message: string, stderr: string);
+}
+/** Run `docker <args>` and return trimmed stdout, or throw `DockerCliError`
+ *  with stderr folded into the message. Never logs anything itself — a
+ *  caller passing `-e CRTRD_TOKEN=...` in `args` must not print `args`. */
+export declare function docker(args: string[]): Promise<string>;

package/dist/docker-cli.js

@@ -0,0 +1,30 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/** A `docker` CLI invocation that exited non-zero. Carries stderr separately
+ *  so callers can fold it into a more specific message without re-parsing. */
+export class DockerCliError extends Error {
+    stderr;
+    constructor(message, stderr) {
+        super(message);
+        this.name = 'DockerCliError';
+        this.stderr = stderr;
+    }
+}
+/** Run `docker <args>` and return trimmed stdout, or throw `DockerCliError`
+ *  with stderr folded into the message. Never logs anything itself — a
+ *  caller passing `-e CRTRD_TOKEN=...` in `args` must not print `args`. */
+export async function docker(args) {
+    try {
+        const { stdout } = await execFileAsync('docker', args, { maxBuffer: 16 * 1024 * 1024 });
+        return stdout.trim();
+    }
+    catch (error) {
+        const stderr = isExecError(error) ? error.stderr.trim() : '';
+        const message = error instanceof Error ? error.message : String(error);
+        throw new DockerCliError(`docker ${args[0] ?? ''} failed: ${stderr || message}`, stderr);
+    }
+}
+function isExecError(error) {
+    return typeof error === 'object' && error !== null && typeof error.stderr === 'string';
+}

package/dist/health.d.ts

@@ -0,0 +1,7 @@
+/** Poll `<baseUrl>/healthz` until it answers 200, `opts.timeoutMs` elapses,
+ *  or `opts.isAlive` reports the container already exited. */
+export declare function waitForHealthy(baseUrl: string, headers: Record<string, string>, opts: {
+    timeoutMs: number;
+    intervalMs: number;
+    isAlive?: () => Promise<boolean>;
+}): Promise<void>;

package/dist/health.js

@@ -0,0 +1,38 @@
+import { request } from 'node:http';
+/** Poll `<baseUrl>/healthz` until it answers 200, `opts.timeoutMs` elapses,
+ *  or `opts.isAlive` reports the container already exited. */
+export async function waitForHealthy(baseUrl, headers, opts) {
+    const deadline = Date.now() + opts.timeoutMs;
+    let lastError;
+    while (Date.now() < deadline) {
+        if (opts.isAlive && !(await opts.isAlive())) {
+            throw new Error(`container exited before /healthz answered${lastError ? ` (last probe: ${lastError})` : ''}`);
+        }
+        try {
+            const status = await probe(baseUrl, headers);
+            if (status === 200)
+                return;
+            lastError = `HTTP ${status}`;
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+        }
+        await sleep(opts.intervalMs);
+    }
+    throw new Error(`/healthz did not return 200 within ${opts.timeoutMs}ms (last: ${lastError ?? 'no response'})`);
+}
+function probe(baseUrl, headers) {
+    return new Promise((resolve, reject) => {
+        const url = new URL('/healthz', baseUrl);
+        const req = request(url, { method: 'GET', headers, timeout: 2000 }, (res) => {
+            res.resume();
+            resolve(res.statusCode ?? 0);
+        });
+        req.on('timeout', () => req.destroy(new Error('healthz probe timed out')));
+        req.on('error', reject);
+        req.end();
+    });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import type { Connection, DockerEnvironment, StartOptions } from './types.js';
+export type { Connection, DockerEnvironment, StartOptions };
+/**
+ * Default image tag — the `latest` the release workflow's `publish-image` job
+ * pushes alongside the version tag. Pass `image` to pin a version or to run a
+ * locally built tag (e.g. `crtrd:local`).
+ */
+export declare const DEFAULT_IMAGE = "ghcr.io/crouton-labs/crtrd:latest";
+/** Run the crtrd image, wait until `/healthz` answers 200 through the mapped
+ *  port, and return its connection settings. `stop()` stops and
+ *  removes the container. */
+export declare function start(opts?: StartOptions): Promise<DockerEnvironment>;
+/** Wrap an already-running container by name. Reads its mapped host port and
+ *  `CRTRD_TOKEN` via `docker inspect`. `stop()` only stops the container —
+ *  it does not remove it. */
+export declare function attach(name: string): Promise<DockerEnvironment>;

package/dist/index.js

@@ -0,0 +1,86 @@
+import { randomBytes } from 'node:crypto';
+import { docker } from './docker-cli.js';
+import { waitForHealthy } from './health.js';
+import { CONTAINER_PORT, inspectContainer, isContainerRunning, readHostPortFromInspect, readTokenFromInspect, resolveHostPort, tryReadLogs, } from './inspect.js';
+/**
+ * Default image tag — the `latest` the release workflow's `publish-image` job
+ * pushes alongside the version tag. Pass `image` to pin a version or to run a
+ * locally built tag (e.g. `crtrd:local`).
+ */
+export const DEFAULT_IMAGE = 'ghcr.io/crouton-labs/crtrd:latest';
+const HEALTH_TIMEOUT_MS = 60_000;
+const HEALTH_INTERVAL_MS = 300;
+function generateToken() {
+    return randomBytes(24).toString('hex');
+}
+function generateName() {
+    return `crtrd-env-${randomBytes(6).toString('hex')}`;
+}
+/** Run the crtrd image, wait until `/healthz` answers 200 through the mapped
+ *  port, and return its connection settings. `stop()` stops and
+ *  removes the container. */
+export async function start(opts = {}) {
+    const image = opts.image ?? DEFAULT_IMAGE;
+    const name = opts.name ?? generateName();
+    const token = generateToken();
+    const args = ['run', '-d', '--name', name, '-e', `CRTRD_TOKEN=${token}`];
+    for (const [key, value] of Object.entries(opts.env ?? {})) {
+        args.push('-e', `${key}=${value}`);
+    }
+    if (opts.volume) {
+        args.push('-v', `${opts.volume}:/home/agent/.crouter`);
+    }
+    // Bind loopback explicitly: docker's default publishes to 0.0.0.0, which
+    // would put a daemon holding the caller's provider keys on the LAN behind
+    // nothing but its bearer token.
+    args.push('-p', `127.0.0.1:${opts.port ?? 0}:${CONTAINER_PORT}`);
+    args.push(image);
+    const containerId = await docker(args);
+    const headers = { Authorization: `Bearer ${token}` };
+    let baseUrl;
+    try {
+        const port = await resolveHostPort(containerId);
+        baseUrl = `http://127.0.0.1:${port}`;
+        await waitForHealthy(baseUrl, headers, {
+            timeoutMs: HEALTH_TIMEOUT_MS,
+            intervalMs: HEALTH_INTERVAL_MS,
+            isAlive: () => isContainerRunning(containerId),
+        });
+    }
+    catch (error) {
+        const logs = await tryReadLogs(containerId);
+        await docker(['rm', '-f', containerId]).catch(() => { });
+        throw new Error(`crouter-env-docker: start() container '${name}' (${containerId.slice(0, 12)}) never became healthy: ${error instanceof Error ? error.message : String(error)}${logs ? `\n--- docker logs ---\n${logs}` : ''}`);
+    }
+    return {
+        containerId,
+        name,
+        connection() {
+            return { baseURL: baseUrl, headers };
+        },
+        async stop() {
+            await docker(['rm', '-f', containerId]);
+        },
+    };
+}
+/** Wrap an already-running container by name. Reads its mapped host port and
+ *  `CRTRD_TOKEN` via `docker inspect`. `stop()` only stops the container —
+ *  it does not remove it. */
+export async function attach(name) {
+    const inspection = await inspectContainer(name);
+    const containerId = inspection.Id;
+    const token = readTokenFromInspect(inspection, name);
+    const port = readHostPortFromInspect(inspection, name);
+    const baseUrl = `http://127.0.0.1:${port}`;
+    const headers = { Authorization: `Bearer ${token}` };
+    return {
+        containerId,
+        name,
+        connection() {
+            return { baseURL: baseUrl, headers };
+        },
+        async stop() {
+            await docker(['stop', containerId]);
+        },
+    };
+}

package/dist/inspect.d.ts

@@ -0,0 +1,30 @@
+export declare const CONTAINER_PORT = 7777;
+interface DockerInspectOutput {
+    Id: string;
+    State?: {
+        Running?: boolean;
+    };
+    Config?: {
+        Env?: string[];
+    };
+    NetworkSettings?: {
+        Ports?: Record<string, {
+            HostIp?: string;
+            HostPort?: string;
+        }[] | null>;
+    };
+}
+/** `docker inspect <name>` for one container. Throws a message naming `name`
+ *  when the container does not exist — the caller (`attach()`) surfaces this
+ *  as-is, which is the "attach fails clearly because the container is gone"
+ *  contract. */
+export declare function inspectContainer(name: string): Promise<DockerInspectOutput>;
+export declare function readTokenFromInspect(inspection: DockerInspectOutput, name: string): string;
+export declare function readHostPortFromInspect(inspection: DockerInspectOutput, name: string): number;
+export declare function isContainerRunning(containerId: string): Promise<boolean>;
+export declare function tryReadLogs(containerId: string): Promise<string | undefined>;
+/** `docker port <id> <containerPort>/tcp` prints one host binding per line —
+ *  e.g. `0.0.0.0:54321` and `[::]:54321` for a dual-stack mapping. Take the
+ *  first line's port. */
+export declare function resolveHostPort(containerId: string): Promise<number>;
+export {};

package/dist/inspect.js

@@ -0,0 +1,66 @@
+import { docker } from './docker-cli.js';
+export const CONTAINER_PORT = 7777;
+/** `docker inspect <name>` for one container. Throws a message naming `name`
+ *  when the container does not exist — the caller (`attach()`) surfaces this
+ *  as-is, which is the "attach fails clearly because the container is gone"
+ *  contract. */
+export async function inspectContainer(name) {
+    let stdout;
+    try {
+        stdout = await docker(['inspect', name]);
+    }
+    catch (error) {
+        throw new Error(`crouter-env-docker: attach('${name}') failed — no such container (${error instanceof Error ? error.message : String(error)})`);
+    }
+    const parsed = JSON.parse(stdout);
+    const entry = parsed[0];
+    if (!entry) {
+        throw new Error(`crouter-env-docker: attach('${name}') failed — docker inspect returned no data`);
+    }
+    return entry;
+}
+export function readTokenFromInspect(inspection, name) {
+    const env = inspection.Config?.Env ?? [];
+    const entry = env.find((line) => line.startsWith('CRTRD_TOKEN='));
+    if (!entry) {
+        throw new Error(`crouter-env-docker: attach('${name}') failed — container has no CRTRD_TOKEN env var (was it started by this package's start()?)`);
+    }
+    return entry.slice('CRTRD_TOKEN='.length);
+}
+export function readHostPortFromInspect(inspection, name) {
+    const bindings = inspection.NetworkSettings?.Ports?.[`${CONTAINER_PORT}/tcp`];
+    const hostPort = bindings?.[0]?.HostPort;
+    if (!hostPort) {
+        throw new Error(`crouter-env-docker: attach('${name}') failed — no host port mapped for ${CONTAINER_PORT}/tcp (is the container running?)`);
+    }
+    return Number(hostPort);
+}
+export async function isContainerRunning(containerId) {
+    try {
+        const state = await docker(['inspect', '-f', '{{.State.Running}}', containerId]);
+        return state === 'true';
+    }
+    catch {
+        return false;
+    }
+}
+export async function tryReadLogs(containerId) {
+    try {
+        return await docker(['logs', '--tail', '50', containerId]);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `docker port <id> <containerPort>/tcp` prints one host binding per line —
+ *  e.g. `0.0.0.0:54321` and `[::]:54321` for a dual-stack mapping. Take the
+ *  first line's port. */
+export async function resolveHostPort(containerId) {
+    const output = await docker(['port', containerId, `${CONTAINER_PORT}/tcp`]);
+    const firstLine = output.split('\n')[0]?.trim() ?? '';
+    const match = firstLine.match(/:(\d+)$/);
+    if (!match) {
+        throw new Error(`crouter-env-docker: could not determine the host port docker mapped for container ${containerId} (docker port output: ${JSON.stringify(output)})`);
+    }
+    return Number(match[1]);
+}

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+export interface Connection {
+    baseURL: string;
+    headers?: Record<string, string>;
+}
+export interface DockerEnvironment {
+    connection(): Connection;
+    /** The container's full id. */
+    containerId: string;
+    /** The container's name — as passed to `start({ name })` or generated, or the name passed to `attach()`. */
+    name: string;
+    /** `start()`'s container: stop and remove. `attach()`'s container: stop only. */
+    stop(): Promise<void>;
+}
+export interface StartOptions {
+    /**
+     * Image to run. Default: `DEFAULT_IMAGE` (`ghcr.io/crouton-labs/crtrd:latest`).
+     * Pass a version tag to pin, or a locally built tag (e.g. `crtrd:local`).
+     */
+    image?: string;
+    /** Extra env vars forwarded into the container — model provider keys, etc. Never logged. */
+    env?: Record<string, string>;
+    /** Container name. A named container is later addressable via `attach()`. Default: a generated random name. */
+    name?: string;
+    /** Named volume mounted at `CRTR_HOME` (`/home/agent/.crouter`). Default: none — an ephemeral, unnamed home. */
+    volume?: string;
+    /** Host port to bind, always on `127.0.0.1`. Default: a random free port docker assigns. */
+    port?: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@crouter/env-docker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.377",
+  "description": "Docker connection manager for the crouter SDK — start, attach to, and stop a crtrd container over the docker CLI. Zero crouter imports.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crouton-labs/crouter.git",
+    "directory": "packages/crouter-env-docker"
+  },
+  "license": "GPL-3.0-only"
+}