glovebox-core 0.5.0

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2026 dterminal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,272 @@
+# glovebox-core
+
+Authoring kit and `glovebox` build CLI for shipping a [Glove](https://github.com/porkytheblack/glove) agent as a sandboxed, network-addressable service. Wrap a built `Glove` runnable, run `glovebox build`, ship the resulting Dockerfile (or nixpacks bundle) to any container host.
+
+> The package is named `glovebox-core` on npm because the unscoped `glovebox` slot is taken by another project. The CLI binary it installs is still called `glovebox`, and the value you import from it is still called `glovebox` — only the install name differs.
+
+## Install
+
+```sh
+pnpm add glovebox-core glovebox-kit
+```
+
+`glovebox-kit` is the in-container runtime; `glovebox build` bakes it into the generated server bundle, so it must resolve at install time. The `glovebox` binary is installed into your project's `node_modules/.bin`.
+
+## What it does
+
+A normal `Glove` agent runs in-process: tools, displays, and storage all live wherever the host process happens to live. Glovebox packages that same agent as a long-running container that exposes one authenticated WebSocket endpoint per session. The agent gets:
+
+- A clean `/work`, `/input`, `/output` filesystem layout, owned by an unprivileged `glovebox` user.
+- A pinned base image with the system tools the agent declares (ffmpeg, pandoc, Playwright, ...).
+- A `FileRef`-based wire protocol so caller files cross the network as references (inline / URL / server-hosted / S3), never raw blobs over WS frames.
+- An auto-injected `environment` skill, `workspace` skill, `/output` hook, and `/clear-workspace` hook.
+
+The build CLI emits a Dockerfile, a `nixpacks.toml` (Railway-flavored alternative), an esbuild server bundle (~150 KB), a manifest, and a generated bearer key. No app code runs at build time besides the entry import that hands over the wrapped runnable.
+
+## Usage
+
+### 1. Wrap a built runnable
+
+`glovebox.wrap(runnable, config)` takes any object that satisfies `IGloveRunnable` (the result of `Glove.build()`) and returns an opaque `GloveboxApp`. The build CLI imports your entry file, reads `default` (or named `app`) from it, and consumes the wrap.
+
+```ts
+// glovebox.ts — the entry the build CLI compiles
+import { Glove } from "glove-core/glove"
+import { Displaymanager } from "glove-core/display-manager"
+import { SqliteStore } from "glove-core"
+import { createAdapter } from "glove-core/models/providers"
+import { z } from "zod"
+import { execFile } from "node:child_process"
+import { promisify } from "node:util"
+import path from "node:path"
+
+import { glovebox, rule, composite } from "glovebox-core"
+
+const exec = promisify(execFile)
+
+const agent = new Glove({
+  store: new SqliteStore({ dbPath: "/work/glove.db", sessionId: "trim" }),
+  model: createAdapter({ provider: "anthropic", model: "claude-sonnet-4-20250514" }),
+  displayManager: new Displaymanager(),
+  systemPrompt:
+    "You trim media files. Inputs land in /input, write trimmed files to /output.",
+  compaction_config: { compaction_instructions: "Summarize the conversation." },
+  serverMode: true,
+})
+  .fold({
+    name: "trim",
+    description: "Trim a media file with ffmpeg.",
+    inputSchema: z.object({
+      file: z.string().describe("Filename in /input"),
+      start: z.string(),
+      duration: z.string(),
+    }),
+    async do(input) {
+      const out = path.join("/output", `trimmed-${input.file}`)
+      await exec("ffmpeg", [
+        "-y", "-i", path.join("/input", input.file),
+        "-ss", input.start, "-t", input.duration, "-c", "copy", out,
+      ])
+      return { status: "success" as const, data: { out } }
+    },
+  })
+  .build()
+
+export default glovebox.wrap(agent, {
+  name: "media-trimmer",
+  base: "glovebox/media",
+  packages: { apt: ["ffmpeg"] },
+  env: {
+    ANTHROPIC_API_KEY: { required: true, secret: true },
+  },
+  storage: {
+    inputs: composite([rule.url(), rule.inline()]),
+    outputs: composite([
+      rule.inline({ below: "1MB" }),
+      rule.localServer({ ttl: "1h" }),
+    ]),
+  },
+  limits: { memory: "1Gi", timeout: "5m" },
+})
+```
+
+### 2. Build
+
+```sh
+glovebox build ./glovebox.ts
+# → ✓ Resolved base image: ghcr.io/porkytheblack/glovebox/media:1.4
+#   ✓ Generated Dockerfile / nixpacks.toml / server bundle / auth key
+#   ✓ Wrote dist/
+```
+
+`dist/` contains:
+
+```
+dist/
+├── Dockerfile         # FROMs the resolved base, copies bundle
+├── nixpacks.toml      # Railway-style alternative
+├── glovebox.json      # manifest (env spec, fs layout, key fingerprint, storage policy)
+├── glovebox.key       # generated bearer (gitignored, 0600)
+├── .env.example       # filled from `env` config
+└── server/
+    ├── index.js       # esbuild bundle (~150 KB)
+    ├── package.json   # only better-sqlite3 as runtime dep
+    └── glovebox.json  # copy for runtime
+```
+
+### 3. Deploy
+
+Anywhere that runs a container or honors nixpacks. The bearer key the build emitted is the one and only credential.
+
+```sh
+docker build -t my-trimmer ./dist
+docker run -p 8080:8080 \
+  -e GLOVEBOX_KEY="$(cat ./dist/glovebox.key)" \
+  -e GLOVEBOX_PUBLIC_URL=https://trimmer.example.com \
+  -e ANTHROPIC_API_KEY=sk-ant-... \
+  my-trimmer
+```
+
+Railway / Render / Fly: point the platform at `dist/nixpacks.toml`, set the same env vars, ship.
+
+## Config reference
+
+```ts
+interface GloveboxConfig {
+  name?: string                                 // defaults to "glovebox-app"
+  version?: string                              // defaults to "0.1.0"
+  base?: BaseImage                              // defaults to "glovebox/base"
+  packages?: { apt?: string[]; pip?: string[]; npm?: string[] }
+  fs?: Record<string, { path: string; writable: boolean }>
+  env?: Record<string, EnvVarSpec>
+  storage?: { inputs?: StoragePolicy; outputs?: StoragePolicy }
+  limits?: { cpu?: string; memory?: string; timeout?: string }
+}
+```
+
+### Base images
+
+| `base` | What's in it | Tag |
+|--------|--------------|-----|
+| `glovebox/base` | Node 20 + glovebox user + standard fs layout | `1.0` |
+| `glovebox/media` | base + ffmpeg, imagemagick, sox, yt-dlp | `1.4` |
+| `glovebox/docs` | base + pandoc, qpdf, pdftk-java, libreoffice headless | `1.2` |
+| `glovebox/python` | base + uv + scientific stack | `1.3` |
+| `glovebox/browser` | base + Playwright + Chromium | `1.1` |
+
+Images are pulled from `ghcr.io/porkytheblack/glovebox/<name>:<tag>`. Override the registry at build time:
+
+```sh
+GLOVEBOX_REGISTRY=registry.my-corp.dev/glovebox glovebox build ./glovebox.ts
+```
+
+A custom `base` like `quay.io/me/img:tag` is passed through verbatim — the per-app Dockerfile then provisions the user, layout, and prebuilt `better-sqlite3` itself.
+
+### Filesystem
+
+Defaults — override per-mount via `fs`:
+
+| Name | Path | Writable |
+|------|------|----------|
+| `work` | `/work` | yes |
+| `input` | `/input` | no (mounted RO at runtime) |
+| `output` | `/output` | yes (swept on `/clear-workspace`) |
+
+The agent receives an environment block referencing these paths plus a `workspace` skill it can call to list current contents.
+
+### Storage policy DSL
+
+Inputs and outputs are independent ordered lists of `{ use, when }` rules. Earlier rules win. Build them with `rule.*` + `composite`:
+
+```ts
+import { rule, composite } from "glovebox-core"
+
+storage: {
+  // Caller can pass URL refs the server fetches; otherwise inline base64.
+  inputs: composite([rule.url(), rule.inline()]),
+
+  // Outputs ≤ 1MB ride back inline; everything else is parked on the server
+  // for an hour and the client picks it up over the authenticated /files route.
+  outputs: composite([
+    rule.inline({ below: "1MB" }),
+    rule.localServer({ ttl: "1h" }),
+  ]),
+}
+```
+
+| Rule | Options | Notes |
+|------|---------|-------|
+| `rule.inline({ below?, above? })` | size bounds | base64 in the WS frame; fine for KB-scale |
+| `rule.localServer({ ttl?, below?, above? })` | `ttl` defaults to `1h` | server-hosted via `GET /files/:id`; backed by sqlite + sweeper |
+| `rule.url({ below?, above? })` | none | inputs only — read-only adapter for caller URLs |
+| `rule.s3({ bucket, region?, prefix?, ... })` | bucket required | requires registering an `S3Storage` adapter in your wrap module's `adapters` export (see `glovebox-kit`) |
+
+`composite([])` throws — every policy needs at least one rule. The kit additionally rejects an outputs policy at boot if it has no terminal rule (`always: true` or `default: true`) or if any referenced adapter isn't registered.
+
+A per-prompt override is allowed on the wire (`outputs_policy` on `ClientPromptMessage`) and merges in front of the configured policy — useful when one specific call needs a different parking spot.
+
+### Env vars
+
+Declared variables show up in `.env.example` and are validated on container boot (`required: true` ones throw if unset). The runtime always reads:
+
+| Variable | Required | Default | Meaning |
+|----------|----------|---------|---------|
+| `GLOVEBOX_KEY` | yes | — | Bearer key matching `key_fingerprint` in `glovebox.json` |
+| `GLOVEBOX_PORT` | no | `8080` | HTTP/WS listen port |
+| `GLOVEBOX_PUBLIC_URL` | no | `http://localhost:<port>` | Used to mint `server` FileRefs the client can reach |
+
+### Limits
+
+Surfaced verbatim through the `environment` skill so the agent can self-throttle. Glovebox does not enforce them — your container runtime does.
+
+## Manifest (`glovebox.json`)
+
+Static description of the deployed app. The kit verifies the bearer matches `key_fingerprint` on boot and rejects mismatches before opening the listener. The manifest is also copied into `server/` so the runtime resolves it via `import.meta.url`.
+
+```ts
+interface Manifest {
+  name: string
+  version: string
+  base: string
+  fs: Record<string, { path: string; writable: boolean }>
+  env: Record<string, ManifestEnvVar>
+  limits?: { cpu?: string; memory?: string; timeout?: string }
+  key_fingerprint: string                      // sha256 prefix "abcd1234...wxyz"
+  storage_policy: { inputs: StoragePolicyEncoded; outputs: StoragePolicyEncoded }
+  packages: { apt?: string[]; pip?: string[]; npm?: string[] }
+  protocol_version: 1
+}
+```
+
+## Wire protocol
+
+One WebSocket per client session. Multiple prompts multiplex via `id`. The full type set lives at `glovebox/protocol`. Client → server: `prompt | abort | display_resolve | display_reject | ping`. Server → client: `event | display_push | display_clear | complete | error | pong`.
+
+Files cross the wire as `FileRef` (`inline | url | server | s3 | gcs`) — never raw bytes. The server's storage adapter for the chosen kind is the one and only thing that touches the byte stream.
+
+## CLI
+
+```
+glovebox build <entry> [--out <dir>] [--name <name>]
+```
+
+`<entry>` is the path to your wrap module. `--out` defaults to `<entry-dir>/dist`. `--name` overrides the manifest name without rebuilding the entry.
+
+## Status
+
+v1. Prompts within a session are serialized — Glove's `PromptMachine` is not safe to invoke concurrently, so the kit chains them. Bearer auth on the WebSocket upgrade; no JWT yet. GCS and Azure storage adapters are deferred to v2 along with multiplexed prompt execution, hot-reload of the wrap module, and the hosted glovebox.dev tier.
+
+## Companion packages
+
+- **[`glovebox-kit`](../glovebox-kit/README.md)** — the in-container runtime that the generated server bundle imports. Register custom storage adapters here.
+- **[`glovebox-client`](../glovebox-client/README.md)** — client SDK for talking to a deployed glovebox.
+
+## Documentation
+
+- [Glovebox Guide](https://glove.dterminal.net/docs/glovebox)
+- [Getting Started](https://glove.dterminal.net/docs/getting-started)
+- [Full Documentation](https://glove.dterminal.net)
+
+## License
+
+MIT

package/dist/chunk-7EPHMP7S.js

@@ -0,0 +1,43 @@
+// src/storage.ts
+function whenFromBounds(opts, fallbackDefault) {
+  const when = {};
+  if (opts?.above) when.sizeAbove = opts.above;
+  if (opts?.below) when.sizeBelow = opts.below;
+  if (!when.sizeAbove && !when.sizeBelow) {
+    if (fallbackDefault) when.default = true;
+    else when.always = true;
+  }
+  return when;
+}
+var rule = {
+  inline: (opts) => ({
+    use: { adapter: "inline" },
+    when: whenFromBounds(opts, true)
+  }),
+  localServer: (opts) => ({
+    use: { adapter: "localServer", options: { ttl: opts?.ttl ?? "1h" } },
+    when: whenFromBounds(opts, true)
+  }),
+  s3: (opts) => ({
+    use: {
+      adapter: "s3",
+      options: { bucket: opts.bucket, region: opts.region, prefix: opts.prefix }
+    },
+    when: whenFromBounds(opts, false)
+  }),
+  url: (opts) => ({
+    use: { adapter: "url" },
+    when: whenFromBounds(opts, false)
+  })
+};
+function composite(rules) {
+  if (rules.length === 0) {
+    throw new Error("composite() requires at least one rule");
+  }
+  return { rules };
+}
+
+export {
+  rule,
+  composite
+};

package/dist/chunk-LPP37JKX.js

@@ -0,0 +1,24 @@
+// src/config.ts
+var DEFAULT_FS = {
+  work: { path: "/work", writable: true },
+  input: { path: "/input", writable: false },
+  output: { path: "/output", writable: true }
+};
+var DEFAULT_INPUTS_POLICY = {
+  rules: [
+    { use: { adapter: "url" }, when: { always: true } },
+    { use: { adapter: "inline" }, when: { default: true } }
+  ]
+};
+var DEFAULT_OUTPUTS_POLICY = {
+  rules: [
+    { use: { adapter: "inline" }, when: { sizeBelow: "1MB" } },
+    { use: { adapter: "localServer", options: { ttl: "1h" } }, when: { default: true } }
+  ]
+};
+
+export {
+  DEFAULT_FS,
+  DEFAULT_INPUTS_POLICY,
+  DEFAULT_OUTPUTS_POLICY
+};

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,422 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import path3 from "path";
+import process2 from "process";
+
+// src/build/index.ts
+import { mkdir as mkdir2, writeFile as writeFile3, rm } from "fs/promises";
+import path2 from "path";
+import { pathToFileURL } from "url";
+
+// src/build/dockerfile.ts
+var DEFAULT_BASE_IMAGE_REGISTRY = "ghcr.io/porkytheblack";
+var KNOWN_BASE_TAGS = {
+  "glovebox/base": "1.0",
+  "glovebox/media": "1.4",
+  "glovebox/docs": "1.2",
+  "glovebox/python": "1.3",
+  "glovebox/browser": "1.1"
+};
+var STANDARD_GLOVEBOX_BASES = /* @__PURE__ */ new Set([
+  "glovebox/base",
+  "glovebox/media",
+  "glovebox/docs",
+  "glovebox/python",
+  "glovebox/browser"
+]);
+function resolveBaseImage(base) {
+  if (base.includes(":") || base.includes("/") && !base.startsWith("glovebox/")) {
+    return base;
+  }
+  const registry = (process.env.GLOVEBOX_REGISTRY ?? DEFAULT_BASE_IMAGE_REGISTRY).replace(/\/$/, "");
+  const tag = KNOWN_BASE_TAGS[base] ?? "latest";
+  return `${registry}/${base}:${tag}`;
+}
+function generateDockerfile(config) {
+  const baseImage = resolveBaseImage(config.base);
+  const isStandardBase = STANDARD_GLOVEBOX_BASES.has(config.base);
+  const apt = config.packages.apt ?? [];
+  const pip = config.packages.pip ?? [];
+  const npm = config.packages.npm ?? [];
+  const lines = [];
+  lines.push(`FROM ${baseImage} AS base`);
+  lines.push("");
+  const needsRoot = apt.length > 0 || pip.length > 0 || npm.length > 0;
+  if (needsRoot) {
+    lines.push("USER root");
+    lines.push("");
+  }
+  if (apt.length > 0) {
+    lines.push("RUN apt-get update && apt-get install -y --no-install-recommends \\");
+    lines.push(`      ${apt.join(" \\\n      ")} \\`);
+    lines.push(" && rm -rf /var/lib/apt/lists/*");
+    lines.push("");
+  }
+  if (pip.length > 0) {
+    lines.push(`RUN pip install --no-cache-dir --break-system-packages ${pip.join(" ")}`);
+    lines.push("");
+  }
+  if (npm.length > 0) {
+    lines.push(`RUN npm install -g ${npm.join(" ")}`);
+    lines.push("");
+  }
+  if (!isStandardBase) {
+    const mountLines = [];
+    for (const mount of Object.values(config.fs)) {
+      mountLines.push(`mkdir -p ${mount.path}`);
+    }
+    lines.push("RUN useradd -m -u 10001 glovebox || true \\");
+    lines.push(` && ${mountLines.join(" \\\n && ")} \\`);
+    const ownLines = [];
+    for (const mount of Object.values(config.fs)) {
+      if (mount.writable) {
+        ownLines.push(`chown glovebox:glovebox ${mount.path}`);
+      } else {
+        ownLines.push(`chown root:root ${mount.path} && chmod 555 ${mount.path}`);
+      }
+    }
+    ownLines.push("mkdir -p /var/glovebox/files");
+    ownLines.push("chown -R glovebox:glovebox /var/glovebox");
+    lines.push(` && ${ownLines.join(" \\\n && ")}`);
+    lines.push("");
+  }
+  lines.push("COPY --chown=glovebox:glovebox server /opt/glovebox-server");
+  lines.push("WORKDIR /opt/glovebox-server");
+  if (isStandardBase) {
+    lines.push("RUN mkdir -p node_modules \\");
+    lines.push(" && ln -sfn /opt/glovebox-prebuilt/node_modules/better-sqlite3 node_modules/better-sqlite3");
+  } else {
+    lines.push("RUN npm install --omit=dev --no-package-lock --no-audit --no-fund");
+  }
+  lines.push("");
+  if (needsRoot) {
+    lines.push("USER glovebox");
+    lines.push("");
+  }
+  lines.push("EXPOSE 8080");
+  lines.push("ENV GLOVEBOX_PORT=8080");
+  lines.push('CMD ["node", "index.js"]');
+  lines.push("");
+  return lines.join("\n");
+}
+
+// src/build/key.ts
+import { createHash, randomBytes } from "crypto";
+import { existsSync } from "fs";
+import { readFile, writeFile } from "fs/promises";
+async function ensureAuthKey(keyPath) {
+  let key;
+  if (existsSync(keyPath)) {
+    key = (await readFile(keyPath, "utf8")).trim();
+    if (!key) {
+      key = generateKey();
+      await writeFile(keyPath, key + "\n", { mode: 384 });
+    }
+  } else {
+    key = generateKey();
+    await writeFile(keyPath, key + "\n", { mode: 384 });
+  }
+  return { key, fingerprint: fingerprintKey(key) };
+}
+function generateKey() {
+  return randomBytes(32).toString("base64url");
+}
+function fingerprintKey(key) {
+  const h = createHash("sha256").update(key).digest("hex");
+  return `${h.slice(0, 8)}...${h.slice(-4)}`;
+}
+
+// src/build/manifest.ts
+function generateManifest(args) {
+  const { config, keyFingerprint } = args;
+  const env = {};
+  for (const [name, spec] of Object.entries(config.env)) {
+    env[name] = {
+      required: spec.required,
+      secret: spec.secret,
+      default: spec.default,
+      description: spec.description
+    };
+  }
+  return {
+    name: config.name,
+    version: config.version,
+    base: config.base,
+    fs: config.fs,
+    env,
+    limits: config.limits,
+    key_fingerprint: keyFingerprint,
+    storage_policy: config.storage,
+    packages: config.packages,
+    protocol_version: 1
+  };
+}
+function generateEnvExample(config) {
+  const lines = [];
+  lines.push("# Auth key for the glovebox server (generated by `glovebox build`)");
+  lines.push("GLOVEBOX_KEY=");
+  lines.push("");
+  lines.push("# Optional: override the listening port (default 8080)");
+  lines.push("# GLOVEBOX_PORT=8080");
+  lines.push("");
+  for (const [name, spec] of Object.entries(config.env)) {
+    if (spec.description) lines.push(`# ${spec.description}`);
+    if (spec.required) lines.push("# (required)");
+    if (spec.secret) lines.push("# (secret)");
+    lines.push(`${name}=${spec.default ?? ""}`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+// src/build/nixpacks.ts
+function generateNixpacks(config) {
+  const apt = config.packages.apt ?? [];
+  const pip = config.packages.pip ?? [];
+  const npm = config.packages.npm ?? [];
+  const nixPkgs = ["nodejs_20", ...apt];
+  if (pip.length > 0) {
+    nixPkgs.push("python311");
+    for (const p of pip) nixPkgs.push(`python311Packages.${p}`);
+  }
+  const lines = [];
+  lines.push("[phases.setup]");
+  lines.push(`nixPkgs = ${JSON.stringify(nixPkgs)}`);
+  lines.push("");
+  lines.push("[phases.install]");
+  lines.push(`cmds = ["cd server && npm install --omit=dev --no-package-lock"]`);
+  lines.push("");
+  if (npm.length > 0) {
+    lines.push("[phases.build]");
+    lines.push(`cmds = [${JSON.stringify(`npm install -g ${npm.join(" ")}`)}]`);
+    lines.push("");
+  }
+  lines.push("[start]");
+  lines.push(`cmd = "node server/index.js"`);
+  lines.push("");
+  lines.push("[variables]");
+  lines.push(`GLOVEBOX_PORT = "8080"`);
+  lines.push("");
+  return lines.join("\n");
+}
+
+// src/build/server-bundle.ts
+import { existsSync as existsSync2 } from "fs";
+import { mkdir, writeFile as writeFile2 } from "fs/promises";
+import { createRequire } from "module";
+import path from "path";
+import { build as esbuild } from "esbuild";
+var requireFromHere = createRequire(import.meta.url);
+var NATIVE_EXTERNALS = ["better-sqlite3"];
+var SYNTHETIC_ENTRY = (wrapEntry, kitEntry) => `import { startGlovebox } from ${JSON.stringify(kitEntry)}
+import * as wrapModule from ${JSON.stringify(wrapEntry)}
+
+const port = Number(process.env.GLOVEBOX_PORT ?? 8080)
+const key = process.env.GLOVEBOX_KEY
+if (!key) {
+  console.error("GLOVEBOX_KEY is required")
+  process.exit(1)
+}
+
+const app = wrapModule.default ?? wrapModule.app
+if (!app || app.__glovebox !== 1) {
+  console.error("Wrap module did not default-export a GloveboxApp")
+  process.exit(1)
+}
+
+const adapters = typeof wrapModule.adapters === "function"
+  ? await wrapModule.adapters()
+  : wrapModule.adapters
+
+const publicBaseUrl = process.env.GLOVEBOX_PUBLIC_URL
+
+await startGlovebox({
+  app,
+  port,
+  key,
+  manifestPath: new URL("./glovebox.json", import.meta.url).pathname,
+  adapters,
+  publicBaseUrl,
+})
+`;
+var PACKAGE_JSON = (appName) => ({
+  name: `${appName}-server`,
+  version: "0.0.0",
+  private: true,
+  type: "module",
+  main: "index.js",
+  dependencies: {
+    "better-sqlite3": "^11.5.0"
+  }
+});
+async function emitServerBundle(args) {
+  const { wrapEntry, outDir, appName } = args;
+  if (!existsSync2(wrapEntry)) {
+    throw new Error(`Wrap entry not found: ${wrapEntry}`);
+  }
+  await mkdir(outDir, { recursive: true });
+  let kitEntry;
+  try {
+    kitEntry = requireFromHere.resolve("glovebox-kit");
+  } catch {
+    throw new Error(
+      "Could not resolve glovebox-kit from the glovebox install. Make sure glovebox-kit is installed (it's a dep of glovebox)."
+    );
+  }
+  const entryContents = SYNTHETIC_ENTRY(wrapEntry, kitEntry);
+  await esbuild({
+    stdin: {
+      contents: entryContents,
+      resolveDir: path.dirname(wrapEntry),
+      sourcefile: "synthetic-entry.ts",
+      loader: "ts"
+    },
+    outfile: path.join(outDir, "index.js"),
+    bundle: true,
+    platform: "node",
+    format: "esm",
+    target: "node20",
+    external: NATIVE_EXTERNALS,
+    // Mark the dynamic-import-only paths so esbuild doesn't choke if user's
+    // wrap module pulls in optional providers (anthropic, openai, bedrock).
+    logLevel: "error",
+    banner: {
+      // ESM in Node sometimes needs createRequire for transitive CJS modules.
+      js: `import { createRequire as __glb_createRequire } from "node:module";
+const require = __glb_createRequire(import.meta.url);`
+    }
+  });
+  await writeFile2(
+    path.join(outDir, "package.json"),
+    JSON.stringify(PACKAGE_JSON(appName), null, 2) + "\n"
+  );
+}
+
+// src/build/index.ts
+async function build(args) {
+  const entry = path2.resolve(args.entry);
+  const entryDir = path2.dirname(entry);
+  const outDir = path2.resolve(args.outDir ?? path2.join(entryDir, "dist"));
+  const mod = await import(pathToFileURL(entry).href);
+  const app = mod.default ?? mod.app;
+  if (!app || app.__glovebox !== 1) {
+    throw new Error(
+      `Entry ${entry} did not default-export a GloveboxApp. Did you call glovebox.wrap(...)?`
+    );
+  }
+  const config = { ...app.config };
+  if (args.name) config.name = args.name;
+  await rm(outDir, { recursive: true, force: true });
+  await mkdir2(outDir, { recursive: true });
+  const keyPath = path2.join(outDir, "glovebox.key");
+  const { fingerprint } = await ensureAuthKey(keyPath);
+  const dockerfile = generateDockerfile(config);
+  const nixpacks = generateNixpacks(config);
+  const manifest = generateManifest({ config, keyFingerprint: fingerprint });
+  const envExample = generateEnvExample(config);
+  await writeFile3(path2.join(outDir, "Dockerfile"), dockerfile);
+  await writeFile3(path2.join(outDir, "nixpacks.toml"), nixpacks);
+  await writeFile3(path2.join(outDir, "glovebox.json"), JSON.stringify(manifest, null, 2) + "\n");
+  await writeFile3(path2.join(outDir, ".env.example"), envExample);
+  const serverDir = path2.join(outDir, "server");
+  await emitServerBundle({ wrapEntry: entry, outDir: serverDir, appName: config.name });
+  await writeFile3(
+    path2.join(serverDir, "glovebox.json"),
+    JSON.stringify(manifest, null, 2) + "\n"
+  );
+  return {
+    outDir,
+    baseImage: resolveBaseImage(config.base),
+    keyFingerprint: fingerprint,
+    packages: {
+      apt: config.packages.apt?.length ?? 0,
+      pip: config.packages.pip?.length ?? 0,
+      npm: config.packages.npm?.length ?? 0
+    }
+  };
+}
+
+// src/cli.ts
+function parseArgs(argv) {
+  const command = argv[0];
+  const positional = [];
+  const flags = {};
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq !== -1) {
+        flags[a.slice(2, eq)] = a.slice(eq + 1);
+      } else {
+        const next = argv[i + 1];
+        if (next && !next.startsWith("--")) {
+          flags[a.slice(2)] = next;
+          i++;
+        } else {
+          flags[a.slice(2)] = true;
+        }
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  return { command, positional, flags };
+}
+var HELP = `glovebox \u2014 build and ship sandboxed Glove agents
+
+Usage:
+  glovebox build <entry> [--out <dir>] [--name <name>]
+
+Commands:
+  build    Compile a wrap module into a deployable artifact (Dockerfile,
+           nixpacks.toml, server bundle, manifest, key).
+`;
+async function main() {
+  const args = parseArgs(process2.argv.slice(2));
+  if (!args.command || args.command === "help" || args.flags.help) {
+    process2.stdout.write(HELP);
+    process2.exit(0);
+  }
+  if (args.command === "build") {
+    const entry = args.positional[0];
+    if (!entry) {
+      console.error("error: missing entry path");
+      console.error("usage: glovebox build <entry>");
+      process2.exit(1);
+    }
+    const outDir = typeof args.flags.out === "string" ? args.flags.out : void 0;
+    const name = typeof args.flags.name === "string" ? args.flags.name : void 0;
+    const result = await build({ entry, outDir, name });
+    const out = result.outDir;
+    const rel = path3.relative(process2.cwd(), out) || out;
+    process2.stdout.write(`\u2713 Resolved base image: ${result.baseImage}
+`);
+    process2.stdout.write(
+      `\u2713 Resolved packages (${result.packages.apt} apt, ${result.packages.pip} pip, ${result.packages.npm} npm)
+`
+    );
+    process2.stdout.write("\u2713 Generated Dockerfile\n");
+    process2.stdout.write("\u2713 Generated nixpacks.toml\n");
+    process2.stdout.write("\u2713 Generated server bundle\n");
+    process2.stdout.write(`\u2713 Generated auth key (fingerprint: ${result.keyFingerprint})
+`);
+    process2.stdout.write(`\u2713 Wrote ${rel}/
+
+`);
+    process2.stdout.write(`Next:
+`);
+    process2.stdout.write(
+      `  GLOVEBOX_KEY=$(cat ${rel}/glovebox.key) docker run -p 8080:8080 -e GLOVEBOX_KEY <image>
+`
+    );
+    return;
+  }
+  console.error(`unknown command: ${args.command}`);
+  process2.stderr.write(HELP);
+  process2.exit(1);
+}
+main().catch((err) => {
+  console.error(err instanceof Error ? err.stack ?? err.message : err);
+  process2.exit(1);
+});

package/dist/config.d.ts

@@ -0,0 +1,88 @@
+import { StoragePolicyEncoded } from './protocol.js';
+import 'glove-core/core';
+
+/**
+ * Wrap-time configuration for a Glovebox app.
+ *
+ * The developer hands one of these to `glovebox.wrap(runnable, config)` and
+ * the build CLI consumes it to emit a Dockerfile, nixpacks.toml, server
+ * bundle, manifest, and auth key.
+ */
+
+type BaseImage = "glovebox/base" | "glovebox/media" | "glovebox/docs" | "glovebox/python" | "glovebox/browser" | (string & {});
+interface FsMount {
+    path: string;
+    writable: boolean;
+}
+interface EnvVarSpec {
+    required: boolean;
+    secret?: boolean;
+    default?: string;
+    description?: string;
+}
+interface Limits {
+    cpu?: string;
+    memory?: string;
+    timeout?: string;
+}
+interface PackageSpec {
+    apt?: string[];
+    pip?: string[];
+    npm?: string[];
+}
+/**
+ * Storage policy entry. Either passed as a typed `StoragePolicyEncoded` shape
+ * (post-encoding) or as a fluent `StorageRule[]` constructed with the
+ * `rule.*` helpers from `glovebox/storage`.
+ */
+type StoragePolicy = StoragePolicyEncoded | {
+    __rules: StoragePolicyEncoded["rules"];
+};
+interface GloveboxConfig {
+    /** Display name for the app, defaults to the package directory name. */
+    name?: string;
+    /** Semver. Defaults to "0.1.0". */
+    version?: string;
+    /** Base image to extend. Defaults to "glovebox/base". */
+    base?: BaseImage;
+    /** Extra system or language packages to install on top of the base. */
+    packages?: PackageSpec;
+    /** Filesystem mounts inside the container. */
+    fs?: Record<string, FsMount>;
+    /** Declared environment variables. The runtime validates these on boot. */
+    env?: Record<string, EnvVarSpec>;
+    /** Storage policies for inputs (client → server) and outputs (server → client). */
+    storage?: {
+        inputs?: StoragePolicy;
+        outputs?: StoragePolicy;
+    };
+    /** Resource limits and timeout. Surfaced to the agent via the `environment` skill. */
+    limits?: Limits;
+}
+/**
+ * Opaque marker type returned by `glovebox.wrap`. The runtime introspects this
+ * to discover the runnable and the resolved config.
+ */
+interface GloveboxApp {
+    readonly __glovebox: 1;
+    readonly runnable: unknown;
+    readonly config: ResolvedGloveboxConfig;
+}
+interface ResolvedGloveboxConfig {
+    name: string;
+    version: string;
+    base: string;
+    packages: PackageSpec;
+    fs: Record<string, FsMount>;
+    env: Record<string, EnvVarSpec>;
+    storage: {
+        inputs: StoragePolicyEncoded;
+        outputs: StoragePolicyEncoded;
+    };
+    limits: Limits;
+}
+declare const DEFAULT_FS: Record<string, FsMount>;
+declare const DEFAULT_INPUTS_POLICY: StoragePolicyEncoded;
+declare const DEFAULT_OUTPUTS_POLICY: StoragePolicyEncoded;
+
+export { type BaseImage, DEFAULT_FS, DEFAULT_INPUTS_POLICY, DEFAULT_OUTPUTS_POLICY, type EnvVarSpec, type FsMount, type GloveboxApp, type GloveboxConfig, type Limits, type PackageSpec, type ResolvedGloveboxConfig, type StoragePolicy };

package/dist/config.js

@@ -0,0 +1,10 @@
+import {
+  DEFAULT_FS,
+  DEFAULT_INPUTS_POLICY,
+  DEFAULT_OUTPUTS_POLICY
+} from "./chunk-LPP37JKX.js";
+export {
+  DEFAULT_FS,
+  DEFAULT_INPUTS_POLICY,
+  DEFAULT_OUTPUTS_POLICY
+};

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import { GloveboxConfig, GloveboxApp } from './config.js';
+export { BaseImage, DEFAULT_FS, DEFAULT_INPUTS_POLICY, DEFAULT_OUTPUTS_POLICY, EnvVarSpec, FsMount, Limits, PackageSpec, ResolvedGloveboxConfig, StoragePolicy } from './config.js';
+export { ClientAbortMessage, ClientDisplayRejectMessage, ClientDisplayResolveMessage, ClientMessage, ClientPingMessage, ClientPromptMessage, FileRef, FileRefGcs, FileRefInline, FileRefS3, FileRefServer, FileRefUrl, Manifest, ManifestEnvVar, OutputsPolicyOverride, ServerCompleteMessage, ServerDisplayClearMessage, ServerDisplayPushMessage, ServerErrorMessage, ServerEventMessage, ServerMessage, ServerPongMessage, StoragePolicyEncoded, SubscriberEventType, WireSlot } from './protocol.js';
+export { InlineOptions, LocalServerOptions, S3Options, UrlOptions, composite, rule } from './storage.js';
+import 'glove-core/core';
+
+/**
+ * Authoring entry point for Glovebox apps.
+ *
+ *     import { glovebox, rule, composite } from "glovebox-core"
+ *     import { agent } from "./my-agent"
+ *
+ *     export default glovebox.wrap(agent, {
+ *       base: "glovebox/media",
+ *       packages: { apt: ["ffmpeg"] },
+ *       storage: {
+ *         outputs: composite([rule.inline({ below: "1MB" }), rule.localServer({ ttl: "1h" })]),
+ *       },
+ *     })
+ */
+
+/**
+ * Wrap a built Glove runnable into a deployable Glovebox app.
+ *
+ * The returned object is opaque from the developer's perspective. At runtime
+ * (inside the container), `glovebox-kit` reads it to discover the runnable
+ * and the resolved config, then injects glovebox-flavored skills, hooks, and
+ * mentions on top.
+ */
+declare function wrap<R>(runnable: R, config?: GloveboxConfig): GloveboxApp;
+declare const glovebox: {
+    wrap: typeof wrap;
+};
+
+export { GloveboxApp, GloveboxConfig, glovebox };

package/dist/index.js

@@ -0,0 +1,48 @@
+import {
+  DEFAULT_FS,
+  DEFAULT_INPUTS_POLICY,
+  DEFAULT_OUTPUTS_POLICY
+} from "./chunk-LPP37JKX.js";
+import "./chunk-ACURXCF6.js";
+import {
+  composite,
+  rule
+} from "./chunk-7EPHMP7S.js";
+
+// src/index.ts
+function resolvePolicy(p, fallback) {
+  if (!p) return fallback;
+  if ("__rules" in p) return { rules: p.__rules };
+  return p;
+}
+function resolve(config) {
+  return {
+    name: config.name ?? "glovebox-app",
+    version: config.version ?? "0.1.0",
+    base: config.base ?? "glovebox/base",
+    packages: config.packages ?? {},
+    fs: config.fs ?? DEFAULT_FS,
+    env: config.env ?? {},
+    storage: {
+      inputs: resolvePolicy(config.storage?.inputs, DEFAULT_INPUTS_POLICY),
+      outputs: resolvePolicy(config.storage?.outputs, DEFAULT_OUTPUTS_POLICY)
+    },
+    limits: config.limits ?? {}
+  };
+}
+function wrap(runnable, config = {}) {
+  return {
+    __glovebox: 1,
+    runnable,
+    config: resolve(config)
+  };
+}
+var glovebox = { wrap };
+export {
+  DEFAULT_FS,
+  DEFAULT_INPUTS_POLICY,
+  DEFAULT_OUTPUTS_POLICY,
+  composite,
+  glovebox,
+  rule
+};

package/dist/protocol.d.ts

@@ -0,0 +1,181 @@
+import { SubscriberEvent } from 'glove-core/core';
+
+/**
+ * Wire protocol shared by glovebox, glovebox-kit, and glovebox-client.
+ *
+ * One WebSocket per client session. Authenticated on upgrade with
+ * `Authorization: Bearer <key>`. Multiple prompts multiplexed by `id`.
+ */
+
+type FileRefInline = {
+    kind: "inline";
+    name: string;
+    mime: string;
+    /** base64-encoded bytes */
+    data: string;
+};
+type FileRefUrl = {
+    kind: "url";
+    name: string;
+    mime?: string;
+    url: string;
+    headers?: Record<string, string>;
+};
+type FileRefServer = {
+    kind: "server";
+    name: string;
+    mime: string;
+    size: number;
+    id: string;
+    url: string;
+};
+type FileRefS3 = {
+    kind: "s3";
+    name: string;
+    mime?: string;
+    bucket: string;
+    key: string;
+    region?: string;
+};
+type FileRefGcs = {
+    kind: "gcs";
+    name: string;
+    mime?: string;
+    bucket: string;
+    object: string;
+};
+type FileRef = FileRefInline | FileRefUrl | FileRefServer | FileRefS3 | FileRefGcs;
+/**
+ * Wire-side name of a subscriber event. Derived directly from glove-core's
+ * `SubscriberEvent` discriminated union so new events added there flow into
+ * the wire protocol automatically — no hand-maintained mirror to drift.
+ */
+type SubscriberEventType = SubscriberEvent["type"];
+interface WireSlot<I = unknown> {
+    id: string;
+    renderer: string;
+    input: I;
+}
+type ClientPromptMessage = {
+    type: "prompt";
+    id: string;
+    text: string;
+    inputs?: Record<string, FileRef>;
+    /** Optional per-request override for output storage policy. */
+    outputs_policy?: OutputsPolicyOverride;
+};
+type ClientAbortMessage = {
+    type: "abort";
+    id: string;
+};
+type ClientDisplayResolveMessage = {
+    type: "display_resolve";
+    slot_id: string;
+    value: unknown;
+};
+type ClientDisplayRejectMessage = {
+    type: "display_reject";
+    slot_id: string;
+    error: unknown;
+};
+type ClientPingMessage = {
+    type: "ping";
+    ts: number;
+};
+type ClientMessage = ClientPromptMessage | ClientAbortMessage | ClientDisplayResolveMessage | ClientDisplayRejectMessage | ClientPingMessage;
+type ServerEventMessage = {
+    type: "event";
+    id: string;
+    event_type: SubscriberEventType;
+    data: unknown;
+};
+type ServerDisplayPushMessage = {
+    type: "display_push";
+    slot: WireSlot;
+};
+type ServerDisplayClearMessage = {
+    type: "display_clear";
+    slot_id: string;
+};
+type ServerCompleteMessage = {
+    type: "complete";
+    id: string;
+    message: string;
+    outputs: Record<string, FileRef>;
+};
+type ServerErrorMessage = {
+    type: "error";
+    id: string;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+type ServerPongMessage = {
+    type: "pong";
+    ts: number;
+};
+type ServerMessage = ServerEventMessage | ServerDisplayPushMessage | ServerDisplayClearMessage | ServerCompleteMessage | ServerErrorMessage | ServerPongMessage;
+type OutputsPolicyOverride = {
+    /** Force inline below this size. */
+    inline_below?: string;
+    /** Direct uploads to this S3 bucket. Caller must trust server with creds. */
+    s3?: {
+        bucket: string;
+        region?: string;
+        prefix?: string;
+    };
+    /** Time-to-live for the local server adapter. */
+    server_ttl?: string;
+};
+interface ManifestEnvVar {
+    required: boolean;
+    secret?: boolean;
+    default?: string;
+    description?: string;
+}
+interface Manifest {
+    name: string;
+    version: string;
+    base: string;
+    fs: Record<string, {
+        path: string;
+        writable: boolean;
+    }>;
+    env: Record<string, ManifestEnvVar>;
+    limits?: {
+        cpu?: string;
+        memory?: string;
+        timeout?: string;
+    };
+    /** SHA-256 prefix of the auth key (8 chars + ... + 4 chars formatting on display). */
+    key_fingerprint: string;
+    storage_policy: {
+        inputs: StoragePolicyEncoded;
+        outputs: StoragePolicyEncoded;
+    };
+    packages: {
+        apt?: string[];
+        pip?: string[];
+        npm?: string[];
+    };
+    /** Glovebox protocol version. */
+    protocol_version: 1;
+}
+/** Wire-encoded storage policy. Adapters are referenced by name. */
+type StoragePolicyEncoded = {
+    rules: Array<{
+        use: {
+            adapter: string;
+            options?: Record<string, unknown>;
+        };
+        when: {
+            sizeAbove?: string;
+            sizeBelow?: string;
+            always?: boolean;
+            default?: boolean;
+        };
+    }>;
+};
+
+export type { ClientAbortMessage, ClientDisplayRejectMessage, ClientDisplayResolveMessage, ClientMessage, ClientPingMessage, ClientPromptMessage, FileRef, FileRefGcs, FileRefInline, FileRefS3, FileRefServer, FileRefUrl, Manifest, ManifestEnvVar, OutputsPolicyOverride, ServerCompleteMessage, ServerDisplayClearMessage, ServerDisplayPushMessage, ServerErrorMessage, ServerEventMessage, ServerMessage, ServerPongMessage, StoragePolicyEncoded, SubscriberEventType, WireSlot };

package/dist/protocol.js

@@ -0,0 +1 @@
+import "./chunk-ACURXCF6.js";

package/dist/storage.d.ts

@@ -0,0 +1,48 @@
+import { StoragePolicyEncoded } from './protocol.js';
+import 'glove-core/core';
+
+/**
+ * Wrap-time storage policy DSL.
+ *
+ * Usage:
+ *
+ *     storage: {
+ *       inputs:  composite([rule.url(), rule.s3({ bucket: "in" })]),
+ *       outputs: composite([
+ *         rule.inline({ below: "1MB" }),
+ *         rule.localServer({ ttl: "1h" }),
+ *       ]),
+ *     }
+ */
+
+type Rule = StoragePolicyEncoded["rules"][number];
+interface InlineOptions {
+    below?: string;
+    above?: string;
+}
+interface LocalServerOptions {
+    ttl?: string;
+    below?: string;
+    above?: string;
+}
+interface S3Options {
+    bucket: string;
+    region?: string;
+    prefix?: string;
+    below?: string;
+    above?: string;
+}
+interface UrlOptions {
+    below?: string;
+    above?: string;
+}
+declare const rule: {
+    inline: (opts?: InlineOptions) => Rule;
+    localServer: (opts?: LocalServerOptions) => Rule;
+    s3: (opts: S3Options) => Rule;
+    url: (opts?: UrlOptions) => Rule;
+};
+/** Combine ordered rules into a storage policy. Earlier rules take priority. */
+declare function composite(rules: Rule[]): StoragePolicyEncoded;
+
+export { type InlineOptions, type LocalServerOptions, type S3Options, type UrlOptions, composite, rule };

package/dist/storage.js

@@ -0,0 +1,8 @@
+import {
+  composite,
+  rule
+} from "./chunk-7EPHMP7S.js";
+export {
+  composite,
+  rule
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "glovebox-core",
+  "version": "0.5.0",
+  "description": "Authoring kit and build CLI for sandboxed Glove agents",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/porkytheblack/glove.git",
+    "directory": "packages/glovebox"
+  },
+  "homepage": "https://github.com/porkytheblack/glove",
+  "bugs": "https://github.com/porkytheblack/glove/issues",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "glovebox": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js",
+      "default": "./dist/protocol.js"
+    },
+    "./storage": {
+      "types": "./dist/storage.d.ts",
+      "import": "./dist/storage.js",
+      "default": "./dist/storage.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js",
+      "default": "./dist/config.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "esbuild": "^0.27.3",
+    "glove-core": "3.0.0",
+    "glovebox-kit": "0.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}