@north-light/crouter-env-docker 0.3.320 → 0.3.322

package/README.md

@@ -1,91 +1,19 @@
 # @north-light/crouter-env-docker
 
-A Docker `Environment` for the [crouter SDK](https://www.npmjs.com/package/@north-light/crouter-sdk) (`@north-light/crouter-sdk`'s `generate()`): run a [`crtrd`](https://github.com/vallum-security/crouter/tree/main/docker) container, wait for it to come up, and hand back the `{ baseUrl, headers }` shape the SDK needs to talk to it.
-
-Zero crouter imports — this package depends on nothing but Node built-ins. It shells out to the `docker` CLI via `child_process` and structurally satisfies the SDK's `Environment` interface (copied by hand into this package's own types, not imported).
-
-## Install
-
-```sh
-npm install @north-light/crouter-env-docker
-```
-
-## Usage
-
-```ts
-import { start } from '@north-light/crouter-env-docker';
-
-const env = await start(); // defaults to ghcr.io/vallum-security/crtrd:latest
-const { baseUrl, headers } = await env.daemon();
-// baseUrl:  http://127.0.0.1:<random free port>
-// headers:  { Authorization: 'Bearer <randomly generated CRTRD_TOKEN>' }
-
-await env.stop(); // stops and removes the container
-```
-
-Named + volume-backed = persistent, addressable by a later `attach()`:
-
-```ts
-import { start, attach } from '@north-light/crouter-env-docker';
-
-await start({ image: 'crtrd:local', name: 'my-agent', volume: 'my-agent-home' });
-// ... later, possibly from a different process ...
-const env = await attach('my-agent');
-const { baseUrl, headers } = await env.daemon();
-await env.stop(); // stops only — the container and its volume survive
-```
-
-### With the crouter SDK
+Run or attach to a `crtrd` Docker container. This package has no dependencies, including on the SDK.
 
 ```ts
 import { start } from '@north-light/crouter-env-docker';
-import { generate } from '@north-light/crouter-sdk';
-import { z } from 'zod';
-
-const env = await start({ image: 'crtrd:local', env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! } });
-
-const result = await generate({
-  prompt: 'Read package.json and report the package name and version.',
-  schema: z.object({ name: z.string(), version: z.string() }),
-  env,
-});
+import Crouter from '@north-light/crouter-sdk';
 
+const env = await start({ volume: 'my-agent-home' });
+const client = new Crouter(env.connection());
+await client.nodes.create({ prompt: 'Read package.json.', root: true });
 await env.stop();
 ```
 
-## API
-
-```ts
-export interface Environment {
-  daemon(): Promise<{ baseUrl?: string; socketPath?: string; headers?: Record<string, string> }>;
-}
-
-export interface DockerEnvironment extends Environment {
-  containerId: string;
-  name: string;
-  stop(): Promise<void>; // stop + remove (start()'s container) or just stop (attach()'s)
-}
-
-export function start(opts?: {
-  image?: string;               // default: DEFAULT_IMAGE (ghcr.io/vallum-security/crtrd:<pin> — see below)
-  env?: Record<string, string>; // forwarded to the container as -e KEY=VALUE (model provider keys, etc)
-  name?: string;                // container name; default: a generated random name
-  volume?: string;              // named volume mounted at CRTR_HOME; default: none (ephemeral home)
-  port?: number;                // host port, always bound to 127.0.0.1; default: a random free port docker assigns
-}): Promise<DockerEnvironment>;
-
-export function attach(name: string): Promise<DockerEnvironment>;
-```
-
-- `start()` generates a random `CRTRD_TOKEN`, passes it into the container as `-e`, and resolves only once `/healthz` answers `200` with that bearer through the mapped host port.
-- `attach(name)` reads the mapped port and `CRTRD_TOKEN` off an already-running container via `docker inspect`. It throws a clear error if the container does not exist, is not running, or was not started with a `CRTRD_TOKEN` env var.
-- The token is never logged.
-- The container port is published to `127.0.0.1` only, never `0.0.0.0` — the daemon holds whatever provider keys you passed in `env`, and must not be reachable from the LAN.
-
-## Default image
-
-`DEFAULT_IMAGE` is `ghcr.io/vallum-security/crtrd:latest`, which the release workflow pushes alongside each version tag. Pass `image` to pin a version, or to run a locally built tag (`crtrd:local`, see [`docker/README.md`](../../docker/README.md)).
+`connection()` returns `{ baseURL, headers }`, ready for `new Crouter(...)`. `start()` creates a container with a generated bearer token, waits for `/healthz`, and `stop()` removes that container. `attach(name)` reads an existing container's mapped port and token; its `stop()` only stops the container.
 
-## Requirements
+`start()` accepts `image`, `env`, `name`, `volume`, and `port`. The port is always bound to `127.0.0.1`; a named volume preserves the crouter home across containers.
 
-The `docker` CLI, reachable and authenticated for whatever registry `image` names, on `PATH`.
+The Docker CLI must be on `PATH` and authenticated for the requested image registry.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import type { DockerEnvironment, Environment, StartOptions } from './types.js';
-export type { DockerEnvironment, Environment, StartOptions };
+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
@@ -7,7 +7,7 @@ export type { DockerEnvironment, Environment, StartOptions };
  */
 export declare const DEFAULT_IMAGE = "ghcr.io/vallum-security/crtrd:latest";
 /** Run the crtrd image, wait until `/healthz` answers 200 through the mapped
- *  port, and return an `Environment` pointed at it. `stop()` stops and
+ *  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

package/dist/index.js

@@ -17,7 +17,7 @@ function generateName() {
     return `crtrd-env-${randomBytes(6).toString('hex')}`;
 }
 /** Run the crtrd image, wait until `/healthz` answers 200 through the mapped
- *  port, and return an `Environment` pointed at it. `stop()` stops and
+ *  port, and return its connection settings. `stop()` stops and
  *  removes the container. */
 export async function start(opts = {}) {
     const image = opts.image ?? DEFAULT_IMAGE;
@@ -55,8 +55,8 @@ export async function start(opts = {}) {
     return {
         containerId,
         name,
-        async daemon() {
-            return { baseUrl, headers };
+        connection() {
+            return { baseURL: baseUrl, headers };
         },
         async stop() {
             await docker(['rm', '-f', containerId]);
@@ -76,8 +76,8 @@ export async function attach(name) {
     return {
         containerId,
         name,
-        async daemon() {
-            return { baseUrl, headers };
+        connection() {
+            return { baseURL: baseUrl, headers };
         },
         async stop() {
             await docker(['stop', containerId]);

package/dist/types.d.ts

@@ -1,19 +1,9 @@
-/**
- * Structural mirror of the crouter SDK's `Environment` interface
- * (`packages/crouter-sdk`, `crouter-sdk-design.md` unit B). Copied by hand,
- * not imported — this package carries zero crouter/SDK dependencies, so a
- * `DockerEnvironment` satisfies the SDK's `Environment` purely by shape. Keep
- * this in sync with the SDK's definition if it changes.
- */
-export interface Environment {
-    /** Where the crtrd for this run is. Called once per `generate()`. */
-    daemon(): Promise<{
-        baseUrl?: string;
-        socketPath?: string;
-        headers?: Record<string, string>;
-    }>;
+export interface Connection {
+    baseURL: string;
+    headers?: Record<string, string>;
 }
-export interface DockerEnvironment extends Environment {
+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()`. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@north-light/crouter-env-docker",
-  "version": "0.3.320",
-  "description": "Docker Environment for the crouter SDK — start, attach to, and stop a crtrd container over the docker CLI. Zero crouter imports.",
+  "version": "0.3.322",
+  "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",