@voicethere/agent 0.1.1 → 0.1.2

package/README.md

@@ -101,14 +101,15 @@ Copy [`templates/agent.ts`](./templates/agent.ts) as a starting point — exhaus
 
 ## Building your agent bundle
 
-**Recommended:** single ESM bundle (esbuild or similar):
+**Recommended:** bundle with the package CLI (same esbuild settings VoiceThere uses in production):
 
 ```bash
-npm install @voicethere/agent esbuild
-npx esbuild agent.ts --bundle --platform=node --format=esm --outfile=dist/agent.js
+npm install @voicethere/agent
+npx @voicethere/agent build
+# or: npx @voicethere/agent build --entry src/agent.ts --outfile dist/agent.js
 ```
 
-Upload `dist/agent.js` (or point `AGENT_BUNDLE_PATH` at it locally). Inlining dependencies avoids runtime `node_modules` resolution inside the sandbox.
+Defaults: entry `agent.ts`, output `dist/agent.js`. Upload the bundle (or point `AGENT_BUNDLE_PATH` at it locally). Inlining dependencies avoids runtime `node_modules` resolution inside the sandbox.
 
 ## Sandbox and security model
 
@@ -227,7 +228,9 @@ Prefer **one esbuild bundle** so production behavior matches `npm run verify:loc
 ## Scripts
 
 ```bash
-npm run build           # library + example bundle
+npm run build           # compile SDK + example bundle (repo dev)
+npm run build:lib       # compile SDK only (tsc → dist/)
+npx @voicethere/agent build   # customer project: bundle agent.ts → dist/agent.js
 npm run verify:local    # sandbox smoke (build + fork bundle)
 npm run test:ci         # typecheck + vitest
 ```

package/dist/build-bundle.d.ts

@@ -0,0 +1,14 @@
+import * as esbuild from "esbuild";
+export interface BuildAgentBundleOptions {
+    /** Agent source entry (TypeScript or JavaScript). */
+    entry: string;
+    /** Output bundle path (typically `dist/agent.js`). */
+    outfile: string;
+    /** Working directory for relative paths. Defaults to `process.cwd()`. */
+    cwd?: string;
+}
+/**
+ * Bundle customer agent source into a single ESM file for the sandboxed child.
+ */
+export declare function buildAgentBundle(options: BuildAgentBundleOptions): Promise<esbuild.BuildResult>;
+//# sourceMappingURL=build-bundle.d.ts.map

package/dist/build-bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-bundle.d.ts","sourceRoot":"","sources":["../src/build-bundle.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AAEnC,MAAM,WAAW,uBAAuB;IACtC,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAoB9B"}

package/dist/build-bundle.js

@@ -0,0 +1,25 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import * as esbuild from "esbuild";
+/**
+ * Bundle customer agent source into a single ESM file for the sandboxed child.
+ */
+export async function buildAgentBundle(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const entry = resolve(cwd, options.entry);
+    const outfile = resolve(cwd, options.outfile);
+    if (!existsSync(entry)) {
+        throw new Error(`Entry not found: ${entry}`);
+    }
+    mkdirSync(dirname(outfile), { recursive: true });
+    return esbuild.build({
+        entryPoints: [entry],
+        bundle: true,
+        platform: "node",
+        format: "esm",
+        outfile,
+        target: "node22",
+        logLevel: "warning",
+    });
+}
+//# sourceMappingURL=build-bundle.js.map

package/dist/build-bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-bundle.js","sourceRoot":"","sources":["../src/build-bundle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE7C,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AAWnC;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAgC;IAEhC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC1C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAE9C,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,oBAAoB,KAAK,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAEjD,OAAO,OAAO,CAAC,KAAK,CAAC;QACnB,WAAW,EAAE,CAAC,KAAK,CAAC;QACpB,MAAM,EAAE,IAAI;QACZ,QAAQ,EAAE,MAAM;QAChB,MAAM,EAAE,KAAK;QACb,OAAO;QACP,MAAM,EAAE,QAAQ;QAChB,QAAQ,EAAE,SAAS;KACpB,CAAC,CAAC;AACL,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Customer-facing CLI — bundle agent source for the VoiceThere sandbox.
+ *
+ *   npx @voicethere/agent build
+ *   npx @voicethere/agent build --entry agent.ts --outfile dist/agent.js
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;GAKG"}

package/dist/cli.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * Customer-facing CLI — bundle agent source for the VoiceThere sandbox.
+ *
+ *   npx @voicethere/agent build
+ *   npx @voicethere/agent build --entry agent.ts --outfile dist/agent.js
+ */
+import { buildAgentBundle } from "./build-bundle.js";
+const DEFAULT_ENTRY = "agent.ts";
+const DEFAULT_OUTFILE = "dist/agent.js";
+function printHelp() {
+    process.stdout.write(`@voicethere/agent — bundle your voice agent for VoiceThere
+
+Usage:
+  npx @voicethere/agent build [options]
+  npx @voicethere/agent [options]          (build is the default command)
+
+Options:
+  --entry, -e <path>     Agent entry file (default: ${DEFAULT_ENTRY})
+  --outfile, -o <path>   Output bundle (default: ${DEFAULT_OUTFILE})
+  --help, -h             Show this help
+
+Example:
+  npm install @voicethere/agent
+  npx @voicethere/agent build --entry src/agent.ts --outfile dist/agent.js
+`);
+}
+function parseBuildArgs(argv) {
+    let entry = DEFAULT_ENTRY;
+    let outfile = DEFAULT_OUTFILE;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--help" || arg === "-h") {
+            printHelp();
+            process.exit(0);
+        }
+        if (arg === "--entry" || arg === "-e") {
+            const value = argv[i + 1];
+            if (!value) {
+                throw new Error(`${arg} requires a path`);
+            }
+            entry = value;
+            i += 1;
+            continue;
+        }
+        if (arg === "--outfile" || arg === "-o") {
+            const value = argv[i + 1];
+            if (!value) {
+                throw new Error(`${arg} requires a path`);
+            }
+            outfile = value;
+            i += 1;
+            continue;
+        }
+        throw new Error(`Unknown option: ${arg}`);
+    }
+    return { entry, outfile };
+}
+async function runBuild(argv) {
+    const { entry, outfile } = parseBuildArgs(argv);
+    await buildAgentBundle({ entry, outfile });
+    process.stdout.write(`Built ${outfile} from ${entry}\n`);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0) {
+        await runBuild([]);
+        return;
+    }
+    if (args[0] === "help" || args[0] === "--help" || args[0] === "-h") {
+        printHelp();
+        return;
+    }
+    if (args[0] === "build") {
+        await runBuild(args.slice(1));
+        return;
+    }
+    if (args[0]?.startsWith("-")) {
+        await runBuild(args);
+        return;
+    }
+    process.stderr.write(`Unknown command: ${args[0]}\n\n`);
+    printHelp();
+    process.exit(1);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`agent build failed: ${message}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voicethere/agent",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "VoiceThere customer agent SDK — IPC types and runtime helpers for sandboxed child bundles",
   "type": "module",
   "exports": {
@@ -9,13 +9,16 @@
       "import": "./dist/index.js"
     }
   },
+  "bin": "./dist/cli.js",
   "files": [
     "dist",
     "templates",
     "README.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json && esbuild examples/agent.ts --bundle --platform=node --format=esm --outfile=dist/agent.js",
+    "build:lib": "tsc -p tsconfig.json",
+    "build:example": "node dist/cli.js build --entry examples/agent.ts --outfile dist/agent.js",
+    "build": "npm run build:lib && npm run build:example",
     "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json",
     "test": "vitest run",
     "test:ci": "npm run typecheck && npm run build && npm run test",
@@ -45,14 +48,14 @@
   },
   "license": "UNLICENSED",
   "dependencies": {
-    "@node-webrtc-rust/sdk": "0.5.2"
+    "@node-webrtc-rust/sdk": "0.5.2",
+    "esbuild": "^0.25.12"
   },
   "peerDependencies": {
     "@node-webrtc-rust/sdk": ">=0.5.2"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
-    "esbuild": "^0.25.12",
     "tsx": "^4.19.2",
     "typescript": "^5.7.0",
     "vitest": "^2.1.8"

package/templates/README.md

@@ -17,8 +17,9 @@ Full starter bundle covering every speech event from `@node-webrtc-rust/sdk/voic
 **Build:**
 
 ```bash
-npm install @voicethere/agent esbuild
-npx esbuild agent.ts --bundle --platform=node --format=esm --outfile=dist/agent.js
+npm install @voicethere/agent
+npx @voicethere/agent build
+# optional: --entry agent.ts --outfile dist/agent.js
 ```
 
 **Verify sandbox (no WebRTC):** from the agent repo, `npm run verify:local` after building your bundle.

package/templates/agent.ts

@@ -6,7 +6,7 @@
  *
  * Build:
  *   npm install @voicethere/agent
- *   npx esbuild agent.ts --bundle --platform=node --format=esm --outfile=dist/agent.js
+ *   npx @voicethere/agent build
  *
  * Voice E2E (VoiceThere agent runner — platform or internal deployment):
  *   AGENT_BUNDLE_PATH=./dist/agent.js npm run start