@desplega.ai/agent-env 0.0.0-stage → 0.3.0

package/examples/agent-swarm/compose.agent-env.yaml

@@ -0,0 +1,101 @@
+x-workspace: &workspace
+  - .:/workspace
+  - dependencies:/workspace/node_modules
+  - ui-dependencies:/workspace/apps/ui/node_modules
+  - templates-dependencies:/workspace/apps/templates-ui/node_modules
+  - evals-dependencies:/workspace/apps/evals/node_modules
+  - catalog-dependencies:/workspace/packages/model-catalog/node_modules
+  - routing-dependencies:/workspace/packages/model-routing/node_modules
+  - e2e-dependencies:/workspace/packages/ui-e2e/node_modules
+  - bun-cache:/root/.bun/install/cache
+
+services:
+  setup:
+    image: oven/bun:1.4.4
+    working_dir: /workspace
+    command: ["bun", "--no-env-file", "install", "--frozen-lockfile", "--ignore-scripts"]
+    volumes: *workspace
+  api:
+    image: oven/bun:1.4.4
+    working_dir: /workspace
+    command: ["bun", "--no-env-file", "--expose-gc", "src/http.ts"]
+    depends_on:
+      setup:
+        condition: service_completed_successfully
+    environment:
+      AGENT_SWARM_API_KEY: ${AGENT_SWARM_API_KEY:?Provide a test-only API key through a private env file}
+      DATABASE_PATH: /data/agent-swarm.sqlite
+      AGENT_FS_LOCAL_DIR: /data/files
+      NODE_ENV: development
+      PORT: "3013"
+      MCP_BASE_URL: http://api:3013
+      APP_URL: http://localhost:4574
+      CORS_ALLOWED_ORIGINS: http://localhost:4574,http://${AGENT_SWARM_INSTANCE:-swarm-example}.localhost:4574
+      DESPLEGA_TELEMETRY_ENV: test
+      ANONYMIZED_TELEMETRY: "false"
+      CAPABILITIES: core,task,kv,skills,repo
+      HEARTBEAT_DISABLE: "true"
+      HEARTBEAT_CHECKLIST_DISABLE: "true"
+      TASK_AUTO_TITLE_ENABLED: "false"
+      RUNTIME_POOLS_ENABLED: "false"
+      CHAT_SDK_ENABLED: "false"
+      SLACK_DISABLE: "true"
+      GITHUB_DISABLE: "true"
+      GITLAB_DISABLE: "true"
+      AZURE_DEVOPS_DISABLE: "true"
+      BITBUCKET_DISABLE: "true"
+      AGENTMAIL_DISABLE: "true"
+      LINEAR_DISABLE: "true"
+      JIRA_DISABLE: "true"
+      OAUTH_KEEPALIVE_DISABLE: "true"
+      OAUTH_REFRESH_SWEEP_DISABLE: "true"
+    volumes:
+      - .:/workspace:ro
+      - dependencies:/workspace/node_modules
+      - ui-dependencies:/workspace/apps/ui/node_modules
+      - templates-dependencies:/workspace/apps/templates-ui/node_modules
+      - evals-dependencies:/workspace/apps/evals/node_modules
+      - catalog-dependencies:/workspace/packages/model-catalog/node_modules
+      - routing-dependencies:/workspace/packages/model-routing/node_modules
+      - e2e-dependencies:/workspace/packages/ui-e2e/node_modules
+      - data:/data
+    ports: ["127.0.0.1:4313:3013"]
+    healthcheck:
+      test: ["CMD", "bun", "--no-env-file", "-e", "fetch('http://127.0.0.1:3013/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
+      interval: 2s
+      timeout: 3s
+      retries: 25
+  ui:
+    image: oven/bun:1.4.4
+    working_dir: /workspace/apps/ui
+    command:
+      - bun
+      - --no-env-file
+      - -e
+      - "import {createServer} from 'vite'; const server = await createServer({envDir: false, server: {host: '0.0.0.0', port: 5274, strictPort: true}}); await server.listen(); server.printUrls();"
+    depends_on:
+      setup:
+        condition: service_completed_successfully
+      api:
+        condition: service_healthy
+    environment:
+      VITE_PROXY_TARGET: http://api:3013
+      VITE_ALLOWED_HOSTS: .localhost
+      VITE_PLAUSIBLE_ANALYTICS: "false"
+    volumes: *workspace
+    ports: ["127.0.0.1:4574:5274"]
+    healthcheck:
+      test: ["CMD", "bun", "--no-env-file", "-e", "fetch('http://127.0.0.1:5274').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
+      interval: 2s
+      timeout: 3s
+      retries: 25
+volumes:
+  data: {}
+  dependencies: {}
+  ui-dependencies: {}
+  templates-dependencies: {}
+  evals-dependencies: {}
+  catalog-dependencies: {}
+  routing-dependencies: {}
+  e2e-dependencies: {}
+  bun-cache: {}

package/examples/agent-swarm/verify.mjs

@@ -0,0 +1,55 @@
+import assert from 'node:assert/strict';
+import http from 'node:http';
+
+const instance = process.env.AGENT_SWARM_INSTANCE ?? 'swarm-example';
+const apiKey = process.env.AGENT_SWARM_API_KEY;
+assert.ok(apiKey, 'Provide a test-only AGENT_SWARM_API_KEY.');
+const readOnly = process.argv.includes('--read-only');
+const path = '/api/kv/_/agent-env-example/persistence';
+const value = 'agent-env-local-persistence-check';
+
+function request(port, path, { method = 'GET', authenticated = false, body, named = true } = {}) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({
+      hostname: '127.0.0.1', port, path, method,
+      headers: {
+        host: `${named ? `${instance}.localhost` : 'localhost'}:${port}`,
+        ...(authenticated ? { authorization: `Bearer ${apiKey}` } : {}),
+        ...(body ? { 'content-type': 'application/json' } : {}),
+      },
+    }, response => {
+      let text = '';
+      response.setEncoding('utf8');
+      response.on('data', chunk => { text += chunk; });
+      response.on('end', () => resolve({ status: response.statusCode, text, headers: response.headers }));
+    });
+    req.setTimeout(15000, () => req.destroy(new Error('The local HTTP request timed out.')));
+    req.on('error', reject);
+    req.end(body ? JSON.stringify(body) : undefined);
+  });
+}
+
+for (const named of [true, false]) {
+  const health = await request(4313, '/health', { named });
+  assert.equal(health.status, 200, 'The API health request must succeed.');
+  assert.equal(JSON.parse(health.text).status, 'ok');
+}
+assert.equal((await request(4313, path)).status, 401, 'The API must require authentication.');
+if (!readOnly) {
+  const write = await request(4313, path, { method: 'PUT', authenticated: true, body: { value } });
+  assert.equal(write.status, 200, 'The API write must succeed.');
+  assert.equal(JSON.parse(write.text).value, value);
+}
+for (const port of [4313, 4574]) {
+  const read = await request(port, path, { authenticated: true });
+  assert.equal(read.status, 200, 'The direct or proxied API read must succeed.');
+  assert.equal(JSON.parse(read.text).value, value);
+}
+const ui = await request(4574, '/');
+assert.equal(ui.status, 200, 'The dashboard document must load.');
+assert.match(ui.text, /\/src\/main\.tsx/);
+const module = await request(4574, '/src/main.tsx');
+assert.equal(module.status, 200, 'Vite must transform the real application entry.');
+assert.match(module.headers['content-type'], /javascript/);
+assert.equal((await request(4574, '/health')).status, 200, 'The dashboard proxy must reach the API.');
+console.log(`PASS: ${readOnly ? 'retained KV value' : 'KV write/read'}, authentication, named and selected localhost API routes, dashboard HTML, transformed entry, and dashboard API proxy.`);

package/examples/compose/.dockerignore

@@ -0,0 +1,3 @@
+.env
+.env.*
+agent-env.json

package/examples/compose/Dockerfile

@@ -0,0 +1,4 @@
+FROM node:22-bookworm-slim
+WORKDIR /app
+COPY server.mjs .
+CMD ["node", "server.mjs"]

package/examples/compose/README.md

@@ -0,0 +1,109 @@
+# Compose example
+
+This project builds a Node web service and starts Postgres after its health check succeeds.
+The `tools` service requires the `tools` profile.
+
+Use these commands from this directory:
+
+```sh
+agent-env init
+agent-env env set POSTGRES_PASSWORD < /path/to/private/password-file
+agent-env up --name compose-one
+agent-env up --name compose-two --profile tools
+agent-env exec compose-one --service db -- psql -U postgres -d app -c 'select 1'
+agent-env rm compose-one --purge
+agent-env rm compose-two --purge
+```
+
+The source Compose file stays unchanged. Each instance has its own containers, network, build image, and data volume.
+The web service retains public port 3000 in its metadata. Docker assigns a private loopback port.
+Postgres has no published port and receives no HTTP route.
+
+`loadSpec` accepts one environment name through `env`, as a string or a one-element array.
+The `profile`, `compose-file`, and `env-file` options accept a string or an array of strings.
+Arrays preserve order. Later Compose files and environment files override earlier files.
+
+Named environments use this public configuration:
+
+```json
+{
+  "provider": "compose",
+  "compose": { "files": ["compose.yaml"] },
+  "environments": {
+    "review": {
+      "compose": { "profiles": ["tools"] },
+      "envFiles": [".env.review"],
+      "env": { "POSTGRES_PASSWORD": { "secret": "POSTGRES_PASSWORD" } }
+    }
+  }
+}
+```
+
+An environment value can be a literal string, `{ "secret": "PRIVATE_KEY" }`, or `{ "env": "PROCESS_VARIABLE" }`.
+Store secret values through stdin or a process variable reference. The private store uses mode 0600 outside the checkout.
+Environment files support `export`, comments, quoted values, and multiline quoted values. Their values remain literal, without shell execution or variable expansion.
+Global environment values apply to Docker services and Compose interpolation. Service `environment` entries control which variables enter Compose containers.
+
+For multiple published ports, define one alias for each port:
+
+```json
+{
+  "compose": {
+    "files": ["compose.yaml"],
+    "routes": {
+      "web": { "service": "web", "target": 3000, "port": 3000, "protocol": "http" },
+      "admin": { "service": "web", "target": 9090, "port": 9090, "protocol": "http" }
+    }
+  }
+}
+```
+
+Services without published ports remain internal, including services with `expose` entries.
+Use explicit protocols for ports that do not match common HTTP ports.
+UDP, replicas, host namespaces, static addresses, custom network allocation, and volume driver options require separate support.
+The provider rejects these features. External networks and volumes remain external and survive purge.
+Remote bind and build paths must resolve inside the checkout. Remote binds cannot use files excluded from synchronization.
+The daemon implements Compose volume forks through verified snapshots.
+
+## Integration contract
+
+Import `ComposeProvider` from `src/providers/compose.mjs` and register it under `compose`.
+Docker Compose must support `config --format json`, `config --variables`, and `up --wait`.
+The class implements the Docker provider interface. It uses the Docker helpers for commands, synchronization, SSH, and tunnels.
+`create`, `start`, and `wait` retain desired public ports and discover private backend ports.
+The daemon coordinates snapshot-based forks. Direct provider `fork` calls remain unsupported.
+
+Each `spec.services` and `handle.services` entry has `composeService`.
+Internal entries have `internal: true` and no `port`, `protocol`, or HTTP URL.
+The parent must exclude internal entries when it reserves listeners, changes route focus, and formats URLs.
+Published entries have `port`, `containerPort`, `protocol`, and `transport`.
+Handle entries also have `container` and `hostPort`. Several aliases can refer to one container.
+
+The initialization exports are `createInitialConfig(options)` and `initialize(options)` from `src/init.mjs`.
+Both accept `cwd`, `command`, `port`, and `image`.
+The first returns public configuration. The second writes a new file and returns `{ filename, config }`.
+`initialize` also accepts `config` for the output filename. It never replaces an existing file.
+
+The environment command exports come from `src/environments.mjs`:
+
+- `setEnvironmentSecret({ cwd, environment, key, stdin })` reads a readable stream.
+- `setEnvironmentSecret({ cwd, environment, key, fromEnv })` reads a process variable reference.
+- `listEnvironmentSecrets({ cwd, environment })` returns sorted variable names.
+- `unsetEnvironmentSecret({ cwd, environment, key })` returns whether the variable existed.
+
+These helpers also accept `home` to select the private state directory.
+`setEnvironmentSecret` accepts `env` for an explicit source environment. It rejects a literal `value` argument.
+`readEnvironmentSecrets` and `loadEnvironment` return private values for runtime integration only.
+`parseEnvFile`, `resolveEnvironment`, and `stringList` provide parsing and configuration helpers.
+
+`redactEnvironment(output, values)` accepts an array or an object with private values.
+Compose logs and execution output already use this helper.
+The daemon applies it to Docker logs, execution output, and errors.
+Keep specification values in private daemon state. Never print the full specification or write it into generated public configuration.
+`spec.compose.model` captures the resolved source configuration. It can contain private values.
+This snapshot preserves shell interpolation when the daemon has a different environment.
+It also lets the daemon detect changes to commands, builds, health checks, and other Compose settings.
+`spec.compose.environment` contains private values needed for runtime secrets and redaction.
+
+Run `node test/compose.e2e.mjs` for the provider E2E. It creates and removes only its own resources.
+Run `npm run test:features` for the integrated Compose CLI, snapshot, and worktree flow.

package/examples/compose/compose.yaml

@@ -0,0 +1,36 @@
+services:
+  web:
+    build: .
+    container_name: existing-web-name
+    ports:
+      - "3000:3000"
+    environment:
+      PORT: "3000"
+    depends_on:
+      db:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000').then(r => { if (!r.ok) process.exit(1) }).catch(() => process.exit(1))"]
+      interval: 2s
+      timeout: 2s
+      retries: 30
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_DB: app
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD through agent-env env or an explicit env file}
+    volumes:
+      - data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U postgres -d app"]
+      interval: 2s
+      timeout: 2s
+      retries: 30
+  tools:
+    image: busybox:1.37
+    profiles: [tools]
+    command: ["sh", "-c", "while :; do sleep 3600; done"]
+volumes:
+  data:
+    name: existing-shared-data-name

package/examples/compose/server.mjs

@@ -0,0 +1,6 @@
+import http from 'node:http';
+
+http.createServer((request, response) => {
+  response.setHeader('content-type', 'text/plain');
+  response.end('Compose web is ready. Postgres is internal.\n');
+}).listen(Number(process.env.PORT ?? 3000), '0.0.0.0');

package/examples/hello/agent-env.json

@@ -0,0 +1,20 @@
+{
+  "services": {
+    "web": {
+      "image": "busybox:1.37",
+      "port": 3300,
+      "command": "httpd -f -p 3000 -h /workspace",
+      "containerPort": 3000,
+      "volumes": { "data": "/data" }
+    },
+    "db": {
+      "image": "postgres:16-alpine",
+      "port": 55432,
+      "containerPort": 5432,
+      "protocol": "tcp",
+      "health": "pg_isready -h 127.0.0.1 -U postgres",
+      "env": { "POSTGRES_PASSWORD": "dev-only", "POSTGRES_DB": "app" },
+      "volumes": { "data": "/var/lib/postgresql/data" }
+    }
+  }
+}

package/examples/hello/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>agent-env</title>
+<style>body{font:18px system-ui;background:#f7f7f2;color:#242923;max-width:640px;margin:15vh auto;padding:24px}code{background:#e8ebe2;padding:4px 8px;border-radius:5px}h1{font-size:48px;letter-spacing:-2px}</style>
+<h1>Local address. Any machine.</h1>
+<p>This page runs in an isolated Docker container.</p>
+<p>Your address: <code id="address"></code></p>
+<p>Edit this file, then reload. For SSH instances, run <code>agent-env sync NAME</code> first.</p>
+<script>document.getElementById('address').textContent=location.host</script>
+</html>

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@desplega.ai/agent-env",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Run development services behind stable localhost addresses.",
+  "type": "module",
+  "bin": {
+    "agent-env": "./bin/agent-env.mjs"
+  },
+  "scripts": {
+    "test": "node test/run.mjs",
+    "check": "node scripts/check.mjs",
+    "test:e2e": "node test/run.mjs",
+    "test:core": "node test/run.mjs core",
+    "test:docker": "node test/run.mjs docker",
+    "test:runtime": "node test/runtime-e2e.mjs",
+    "test:features": "node test/run.mjs features",
+    "test:compose": "node test/run.mjs compose",
+    "test:ssh": "node test/run.mjs ssh",
+    "test:s3": "node test/run.mjs s3",
+    "test:cloud": "node test/run.mjs cloud"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE",
+    "examples",
+    "docs",
+    "assets"
+  ],
+  "license": "MIT",
+  "author": "Desplega Labs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/desplega-ai/agent-env.git"
+  },
+  "homepage": "https://github.com/desplega-ai/agent-env#readme",
+  "bugs": {
+    "url": "https://github.com/desplega-ai/agent-env/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}