@johpaz/hive-sdk 0.0.15 → 0.0.16

package/packages/cli/src/commands/add-worker.ts

@@ -0,0 +1,49 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import * as process from "node:process";
+
+function toPascalCase(str: string): string {
+  return str.replace(/[-_](.)/g, (_, char) => char.toUpperCase()).replace(/^(.)/, (_, char) => char.toUpperCase());
+}
+
+async function runAddWorker() {
+  const workerName = process.argv[3];
+
+  if (!workerName) {
+    console.error("Usage: hive add-worker <name>");
+    process.exit(1);
+  }
+
+  const workersDir = join(process.cwd(), "src", "workers");
+  const filePath = join(workersDir, `${workerName}.worker.ts`);
+
+  if (existsSync(filePath)) {
+    console.error(`Worker '${workerName}' already exists.`);
+    process.exit(1);
+  }
+
+  mkdirSync(workersDir, { recursive: true });
+
+  const className = toPascalCase(workerName) + "Worker";
+
+  const content = `import { createWorker } from "@johpaz/hive-sdk";
+
+export const ${workerName}Worker = createWorker({
+  name: "${workerName}",
+  systemPrompt: \`
+    You are the ${className} specialist.
+    You handle tasks related to ${workerName} with precision and expertise.
+    Always provide clear, actionable results.
+  \`,
+});
+
+// Example usage:
+// const result = await ${workerName}Worker.run("Your task here");
+// console.log(result);
+`;
+
+  writeFileSync(filePath, content);
+  console.log(`Created worker: ${filePath}`);
+}
+
+runAddWorker();

package/packages/cli/src/commands/create-app-utils.ts

@@ -0,0 +1,32 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+
+const TEMPLATE_DIR = join(import.meta.dir, "..", "..", "templates", "hive-app");
+
+export function copyTemplate(dest: string, replacements: Record<string, string>) {
+  if (!existsSync(TEMPLATE_DIR)) {
+    throw new Error("Template not found: " + TEMPLATE_DIR);
+  }
+
+  copyDir(TEMPLATE_DIR, dest, replacements);
+}
+
+function copyDir(src: string, dest: string, replacements: Record<string, string>) {
+  for (const entry of readdirSync(src)) {
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    const stat = statSync(srcPath);
+
+    if (stat.isDirectory()) {
+      mkdirSync(destPath, { recursive: true });
+      copyDir(srcPath, destPath, replacements);
+    } else {
+      let content = readFileSync(srcPath, "utf-8");
+      for (const [key, value] of Object.entries(replacements)) {
+        content = content.replaceAll(key, value);
+      }
+      mkdirSync(dirname(destPath), { recursive: true });
+      writeFileSync(destPath, content);
+    }
+  }
+}

package/packages/cli/src/commands/create-app.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it, beforeEach, afterEach } from "bun:test";
+import { existsSync, rmSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import * as process from "node:process";
+
+const TEST_DIR = join(process.cwd(), "test-create-app-output");
+
+describe("hive create-app", () => {
+  beforeEach(() => {
+    // Clean up before each test
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true });
+    }
+  });
+
+  afterEach(() => {
+    // Clean up after each test
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true });
+    }
+  });
+
+  it("generates a hive-app template with correct structure", async () => {
+    const { copyTemplate } = await import("./create-app-utils.ts");
+
+    copyTemplate(TEST_DIR, { "{{APP_NAME}}": "my-test-app" });
+
+    // Check all expected files exist
+    expect(existsSync(join(TEST_DIR, "package.json"))).toBe(true);
+    expect(existsSync(join(TEST_DIR, "hive.config.ts"))).toBe(true);
+    expect(existsSync(join(TEST_DIR, "docker-compose.yml"))).toBe(true);
+    expect(existsSync(join(TEST_DIR, ".env.example"))).toBe(true);
+    expect(existsSync(join(TEST_DIR, ".gitignore"))).toBe(true);
+    expect(existsSync(join(TEST_DIR, "src", "main.ts"))).toBe(true);
+    expect(existsSync(join(TEST_DIR, "src", "agents", "coordinator.ts"))).toBe(true);
+  });
+
+  it("replaces {{APP_NAME}} placeholder in all files", async () => {
+    const { copyTemplate } = await import("./create-app-utils.ts");
+
+    copyTemplate(TEST_DIR, { "{{APP_NAME}}": "my-awesome-app" });
+
+    const packageJson = readFileSync(join(TEST_DIR, "package.json"), "utf-8");
+    expect(packageJson).toContain('"name": "my-awesome-app"');
+
+    const config = readFileSync(join(TEST_DIR, "hive.config.ts"), "utf-8");
+    expect(config).toContain('name: "my-awesome-app"');
+
+    const main = readFileSync(join(TEST_DIR, "src", "main.ts"), "utf-8");
+    expect(main).toContain("Starting my-awesome-app...");
+    expect(main).toContain("my-awesome-app is running at");
+  });
+
+  it("generates valid package.json", async () => {
+    const { copyTemplate } = await import("./create-app-utils.ts");
+
+    copyTemplate(TEST_DIR, { "{{APP_NAME}}": "test-app" });
+
+    const packageJson = JSON.parse(readFileSync(join(TEST_DIR, "package.json"), "utf-8"));
+
+    expect(packageJson.name).toBe("test-app");
+    expect(packageJson.version).toBe("0.1.0");
+    expect(packageJson.type).toBe("module");
+    expect(packageJson.scripts.dev).toBe("bun run src/main.ts");
+    expect(packageJson.scripts.build).toBeDefined();
+    expect(packageJson.dependencies["@johpaz/hive-sdk"]).toBe("latest");
+  });
+
+  it("generates hive.config.ts with correct defaults", async () => {
+    const { copyTemplate } = await import("./create-app-utils.ts");
+
+    copyTemplate(TEST_DIR, { "{{APP_NAME}}": "config-test" });
+
+    const config = readFileSync(join(TEST_DIR, "hive.config.ts"), "utf-8");
+
+    expect(config).toContain('host: process.env.HIVE_HOST ?? "127.0.0.1"');
+    expect(config).toContain('port: Number(process.env.HIVE_PORT ?? 18790)');
+    expect(config).toContain("webchat: { enabled: true }");
+    expect(config).toContain("telegram: { enabled: false }");
+    expect(config).toContain("discord: { enabled: false }");
+    expect(config).toContain("whatsapp: { enabled: false }");
+    expect(config).toContain("slack: { enabled: false }");
+    expect(config).toContain('path: process.env.HIVE_DATA_DIR ?? "./data/hive.db"');
+  });
+
+  it("generates main.ts with all required imports", async () => {
+    const { copyTemplate } = await import("./create-app-utils.ts");
+
+    copyTemplate(TEST_DIR, { "{{APP_NAME}}": "main-test" });
+
+    const main = readFileSync(join(TEST_DIR, "src", "main.ts"), "utf-8");
+
+    expect(main).toContain('from "@johpaz/hive-sdk"');
+    expect(main).toContain("createAgent");
+    expect(main).toContain("startGateway");
+    expect(main).toContain("initializeDatabase");
+    expect(main).toContain("ChannelManager");
+    expect(main).toContain("logger");
+    expect(main).toContain('import config from "../hive.config.ts"');
+    expect(main).toContain("await initializeDatabase()");
+    expect(main).toContain('await startGateway({');
+    expect(main).toContain('process.on("SIGINT"');
+  });
+
+  it("generates coordinator agent with correct config", async () => {
+    const { copyTemplate } = await import("./create-app-utils.ts");
+
+    copyTemplate(TEST_DIR, { "{{APP_NAME}}": "agent-test" });
+
+    const agent = readFileSync(join(TEST_DIR, "src", "agents", "coordinator.ts"), "utf-8");
+
+    expect(agent).toContain('import { createAgent } from "@johpaz/hive-sdk"');
+    expect(agent).toContain('name: "coordinator"');
+    expect(agent).toContain('provider: "openai"');
+    expect(agent).toContain('model: "gpt-4o-mini"');
+  });
+
+  it("generates docker-compose.yml with correct ports", async () => {
+    const { copyTemplate } = await import("./create-app-utils.ts");
+
+    copyTemplate(TEST_DIR, { "{{APP_NAME}}": "docker-test" });
+
+    const docker = readFileSync(join(TEST_DIR, "docker-compose.yml"), "utf-8");
+
+    expect(docker).toContain('image: oven/bun:latest');
+    expect(docker).toContain('"${HIVE_PORT:-18790}:18790"');
+    expect(docker).toContain('HIVE_HOST=0.0.0.0');
+    expect(docker).toContain('HIVE_PORT=18790');
+    expect(docker).toContain('command: ["bun", "run", "src/main.ts"]');
+    expect(docker).toContain('restart: unless-stopped');
+  });
+
+  it("generates .env.example with all required variables", async () => {
+    const { copyTemplate } = await import("./create-app-utils.ts");
+
+    copyTemplate(TEST_DIR, { "{{APP_NAME}}": "env-test" });
+
+    const env = readFileSync(join(TEST_DIR, ".env.example"), "utf-8");
+
+    expect(env).toContain("HIVE_HOST=");
+    expect(env).toContain("HIVE_PORT=");
+    expect(env).toContain("HIVE_DATA_DIR=");
+    expect(env).toContain("OPENAI_API_KEY=");
+    expect(env).toContain("ANTHROPIC_API_KEY=");
+    expect(env).toContain("GOOGLE_API_KEY=");
+    expect(env).toContain("TELEGRAM_BOT_TOKEN=");
+    expect(env).toContain("DISCORD_BOT_TOKEN=");
+    expect(env).toContain("SLACK_BOT_TOKEN=");
+    expect(env).toContain("LOG_LEVEL=");
+  });
+});

package/packages/cli/src/commands/create-app.ts

@@ -0,0 +1,35 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import * as process from "node:process";
+import { copyTemplate } from "./create-app-utils.ts";
+
+async function runCreateApp() {
+  const appName = process.argv[3];
+
+  if (!appName) {
+    console.error("Usage: hive create-app <name>");
+    process.exit(1);
+  }
+
+  const targetDir = join(process.cwd(), appName);
+
+  if (existsSync(targetDir)) {
+    console.error(`Directory '${appName}' already exists.`);
+    process.exit(1);
+  }
+
+  console.log(`Creating Hive app '${appName}'...`);
+
+  copyTemplate(targetDir, {
+    "{{APP_NAME}}": appName,
+  });
+
+  console.log(`\n✅ Created ${appName} in ${targetDir}`);
+  console.log("\nNext steps:");
+  console.log(`  cd ${appName}`);
+  console.log("  bun install");
+  console.log("  cp .env.example .env");
+  console.log("  bun run dev");
+}
+
+runCreateApp();

package/packages/cli/src/index.ts

@@ -7,6 +7,18 @@ switch (command) {
 	case "init":
 		await import("./commands/init.ts");
 		break;
+	case "create-app":
+		await import("./commands/create-app.ts");
+		break;
+	case "add-tool":
+		await import("./commands/add-tool.ts");
+		break;
+	case "add-skill":
+		await import("./commands/add-skill.ts");
+		break;
+	case "add-worker":
+		await import("./commands/add-worker.ts");
+		break;
 	case "run":
 		await import("./commands/run.ts");
 		break;
@@ -32,12 +44,16 @@ function printHelp() {
 Usage: hive <command> [options]
 
 Commands:
-  init         Initialize a new Hive project
-  run          Run the agent
-  test         Test tools or skills
-  trace        View trace execution logs
+  init <name>         Initialize a new Hive agent project
+  create-app <name>   Create a full Hive harness application
+  add-tool <name>     Add a new tool to the current project
+  add-skill <name>    Add a new skill to the current project
+  add-worker <name>   Add a new Bun Worker to the current project
+  run                 Run the agent
+  test                Test tools or skills
+  trace               View trace execution logs
 
 Options:
-  --help, -h   Show this help message
+  --help, -h          Show this help message
 `);
 }

package/packages/cli/templates/hive-app/.env.example

@@ -0,0 +1,17 @@
+# Hive Harness Configuration
+HIVE_HOST=127.0.0.1
+HIVE_PORT=18790
+HIVE_DATA_DIR=./data
+
+# LLM Providers
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GOOGLE_API_KEY=...
+
+# Channels (enable as needed)
+TELEGRAM_BOT_TOKEN=
+DISCORD_BOT_TOKEN=
+SLACK_BOT_TOKEN=
+
+# Logging
+LOG_LEVEL=info

package/packages/cli/templates/hive-app/docker-compose.yml

@@ -0,0 +1,20 @@
+services:
+  app:
+    image: oven/bun:latest
+    working_dir: /app
+    volumes:
+      - .:/app
+      - hive-data:/app/data
+    ports:
+      - "${HIVE_PORT:-18790}:18790"
+    environment:
+      - HIVE_HOST=0.0.0.0
+      - HIVE_PORT=18790
+      - HIVE_DATA_DIR=/app/data
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
+    command: ["bun", "run", "src/main.ts"]
+    restart: unless-stopped
+
+volumes:
+  hive-data:

package/packages/cli/templates/hive-app/hive.config.ts

@@ -0,0 +1,19 @@
+import type { Config } from "@johpaz/hive-sdk";
+
+export default {
+  name: "{{APP_NAME}}",
+  gateway: {
+    host: process.env.HIVE_HOST ?? "127.0.0.1",
+    port: Number(process.env.HIVE_PORT ?? 18790),
+  },
+  channels: {
+    webchat: { enabled: true },
+    telegram: { enabled: false },
+    discord: { enabled: false },
+    whatsapp: { enabled: false },
+    slack: { enabled: false },
+  },
+  database: {
+    path: process.env.HIVE_DATA_DIR ?? "./data/hive.db",
+  },
+} satisfies Config;

package/packages/cli/templates/hive-app/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "{{APP_NAME}}",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "bun run src/main.ts",
+    "start": "bun run src/main.ts",
+    "build": "bun build src/main.ts --outdir dist --target bun"
+  },
+  "dependencies": {
+    "@johpaz/hive-sdk": "latest"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  }
+}

package/packages/cli/templates/hive-app/src/agents/coordinator.ts

@@ -0,0 +1,9 @@
+import { createAgent } from "@johpaz/hive-sdk";
+
+export const coordinatorAgent = await createAgent({
+  name: "coordinator",
+  provider: "openai",
+  model: "gpt-4o-mini",
+  systemPrompt:
+    "You are the coordinator agent. You orchestrate tasks, answer questions, and delegate to specialized agents when needed.",
+});

package/packages/cli/templates/hive-app/src/main.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env bun
+
+import {
+  createAgent,
+  startGateway,
+  initializeDatabase,
+  ChannelManager,
+  logger,
+  loadConfig,
+} from "@johpaz/hive-sdk";
+import config from "../hive.config.ts";
+
+const log = logger.child("app");
+
+async function main() {
+  log.info(`Starting {{APP_NAME}}...`);
+
+  // Initialize database
+  await initializeDatabase();
+
+  // Create the main agent
+  const agent = await createAgent({
+    name: "coordinator",
+    provider: "openai",
+    model: "gpt-4o-mini",
+    systemPrompt:
+      "You are a helpful AI assistant running in a Hive harness. You can use tools, manage tasks, and communicate across channels.",
+  });
+
+  log.info(`Agent ready: ${agent.name}`);
+
+  // Initialize channels
+  const channelManager = new ChannelManager();
+  // TODO: configure channels from hive.config.ts
+
+  // Start the gateway
+  const gateway = await startGateway({
+    host: config.gateway?.host,
+    port: config.gateway?.port,
+    agentId: "coordinator",
+  });
+
+  log.info(`{{APP_NAME}} is running at http://${gateway.hostname}:${gateway.port}`);
+
+  // Graceful shutdown
+  process.on("SIGINT", async () => {
+    log.info("Shutting down...");
+    gateway.stop(true);
+    process.exit(0);
+  });
+}
+
+main().catch((err) => {
+  log.error("Fatal error:", err);
+  process.exit(1);
+});

package/packages/core/src/auth/auth.ts

@@ -0,0 +1,108 @@
+import jwt from "jsonwebtoken";
+import { hashString } from "../utils/crypto.ts";
+import { getDb } from "../storage/SQLiteStorage.ts";
+
+const JWT_SECRET = process.env.JWT_SECRET || "hive-default-jwt-secret-change-in-production";
+const ACCESS_TOKEN_EXPIRY = "15m";
+const REFRESH_TOKEN_EXPIRY = "7d";
+const REFRESH_TOKEN_EXPIRY_SECONDS = 7 * 24 * 60 * 60;
+
+interface AuthTokens {
+  accessToken: string;
+  refreshToken: string;
+  expiresIn: number;
+  tokenType: "Bearer";
+}
+
+interface JwtPayload {
+  userId: string;
+  type: "access" | "refresh";
+}
+
+export async function generateTokens(userId: string): Promise<AuthTokens> {
+  const accessToken = jwt.sign({ userId, type: "access" } satisfies JwtPayload, JWT_SECRET, {
+    expiresIn: ACCESS_TOKEN_EXPIRY,
+  });
+
+  const refreshToken = jwt.sign({ userId, type: "refresh" } satisfies JwtPayload, JWT_SECRET, {
+    expiresIn: REFRESH_TOKEN_EXPIRY,
+  });
+
+  const refreshTokenHash = hashString(refreshToken);
+  const expiresAt = Math.floor(Date.now() / 1000) + REFRESH_TOKEN_EXPIRY_SECONDS;
+
+  const db = getDb();
+  db.run(
+    `INSERT INTO refresh_tokens (user_id, token_hash, expires_at, revoked) 
+     VALUES (?, ?, ?, 0)`,
+    [userId, refreshTokenHash, expiresAt]
+  );
+
+  return {
+    accessToken,
+    refreshToken,
+    expiresIn: 15 * 60,
+    tokenType: "Bearer",
+  };
+}
+
+export async function refreshAccessToken(refreshToken: string): Promise<AuthTokens> {
+  let payload: JwtPayload;
+  try {
+    payload = jwt.verify(refreshToken, JWT_SECRET) as JwtPayload;
+  } catch {
+    throw new Error("Invalid or expired refresh token");
+  }
+
+  if (payload.type !== "refresh") {
+    throw new Error("Invalid token type");
+  }
+
+  const refreshTokenHash = hashString(refreshToken);
+  const db = getDb();
+  const tokenRow = db
+    .query(
+      `SELECT user_id, expires_at, revoked FROM refresh_tokens WHERE token_hash = ?`
+    )
+    .get(refreshTokenHash) as { user_id: string; expires_at: number; revoked: number } | undefined;
+
+  if (!tokenRow) {
+    throw new Error("Refresh token not found");
+  }
+
+  if (tokenRow.revoked === 1) {
+    throw new Error("Refresh token has been revoked");
+  }
+
+  if (tokenRow.expires_at < Math.floor(Date.now() / 1000)) {
+    db.run(`DELETE FROM refresh_tokens WHERE token_hash = ?`, [refreshTokenHash]);
+    throw new Error("Refresh token has expired");
+  }
+
+  db.run(`DELETE FROM refresh_tokens WHERE token_hash = ?`, [refreshTokenHash]);
+
+  return generateTokens(payload.userId);
+}
+
+export async function validateAccessToken(token: string): Promise<{ userId: string } | null> {
+  try {
+    const payload = jwt.verify(token, JWT_SECRET) as JwtPayload;
+    if (payload.type !== "access") {
+      return null;
+    }
+    return { userId: payload.userId };
+  } catch {
+    return null;
+  }
+}
+
+export async function revokeRefreshToken(refreshToken: string): Promise<void> {
+  const refreshTokenHash = hashString(refreshToken);
+  const db = getDb();
+  db.run(`UPDATE refresh_tokens SET revoked = 1 WHERE token_hash = ?`, [refreshTokenHash]);
+}
+
+export async function revokeAllUserTokens(userId: string): Promise<void> {
+  const db = getDb();
+  db.run(`UPDATE refresh_tokens SET revoked = 1 WHERE user_id = ?`, [userId]);
+}

package/packages/core/src/auth/index.ts

@@ -0,0 +1 @@
+export * from "./auth.ts";

package/packages/core/src/canvas/canvas.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "bun:test";
+import { emitCanvas, subscribeCanvas, unsubscribeCanvas } from "./emitter.ts";
+
+describe("canvas emitter", () => {
+  it("subscribes and unsubscribes websocket-like objects", () => {
+    let received: any = null;
+    const ws = {
+      send: (data: string) => { received = JSON.parse(data); },
+    };
+
+    subscribeCanvas(ws);
+    emitCanvas("canvas:render", { component: { id: "test", type: "card" } });
+    unsubscribeCanvas(ws);
+
+    expect(received).toBeDefined();
+    expect(received.type).toBe("canvas:render");
+  });
+
+  it("stops receiving after unsubscribe", () => {
+    let count = 0;
+    const ws = {
+      send: () => { count++; },
+    };
+
+    subscribeCanvas(ws);
+    emitCanvas("canvas:render", { component: { id: "a", type: "card" } });
+    unsubscribeCanvas(ws);
+    emitCanvas("canvas:render", { component: { id: "b", type: "card" } });
+
+    expect(count).toBe(1);
+  });
+});

package/packages/core/src/canvas/emitter.ts

@@ -1,4 +1,4 @@
-import { getDb } from "../storage/SQLiteStorage.ts"
+import { getDb } from "../storage/SQLiteStorage"
 
 export interface CanvasEvent {
   type: CanvasEventType

package/packages/core/src/canvas/index.ts

@@ -1,6 +1,3 @@
-export { createCanvasRenderTool, createCanvasAskTool, createCanvasClearTool, createCanvasTools, createCanvasCardTool, createCanvasProgressTool, createCanvasListTool, createCanvasConfirmTool } from "./canvas-tools.ts";
-export { createA2UISurfaceTool, createA2UIUpdateComponentsTool, createA2UIUpdateDataModelTool, createA2UIDeleteSurfaceTool } from "./a2ui-tools.ts";
-export type { CanvasEvent, CanvasEventType } from "./emitter.ts";
-export { subscribeCanvas, unsubscribeCanvas, emitCanvas, getCanvasSnapshot, removeCanvasComponent } from "./emitter.ts";
-export type { WebSocketLike, CanvasComponent, CanvasMessage, InteractionEvent } from "./CanvasManager.ts";
-export { WebSocketState, CanvasManager, canvasManager } from "./CanvasManager.ts";
+export * from "./CanvasManager.ts";
+export * from "./canvas-tools.ts";
+export * from "./a2ui-tools.ts";