openkrew 0.0.1 → 0.1.2

package/LICENSE

@@ -0,0 +1,75 @@
+License text copyright (c) 2020 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Parameters
+
+Licensor:             OpenKrew (Timothy Carter)
+Licensed Work:        OpenKrew. The Licensed Work is (c) 2026 OpenKrew.
+Additional Use Grant: You may make use of the Licensed Work for any
+                      non-commercial purpose. You may also make production
+                      use of the Licensed Work for internal purposes within
+                      your organization. Your organization includes all of
+                      your affiliates under common control.
+
+                      You may NOT offer the Licensed Work to third parties
+                      on a hosted or embedded basis as a commercial product
+                      or service that competes with the Licensed Work.
+
+                      For purposes of this license:
+
+                      "Non-commercial" means personal, educational,
+                      research, evaluation, or non-profit use.
+
+                      "Internal purposes" means use by your employees and
+                      contractors for the benefit of your organization,
+                      and not for the benefit of third parties.
+Change Date:          March 27, 2029
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact licensing@openkrew.com.
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the third anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.

package/README.md

@@ -0,0 +1,148 @@
+# OpenKrew
+
+<p align="center">
+    <img src="docs/assets/openkrew-logo.png" alt="OpenKrew" width="500">
+</p>
+
+<p align="center">
+  <strong>AI agents on separate machines, working as a team.</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/OpenKrew/openkrew/actions"><img src="https://img.shields.io/github/actions/workflow/status/OpenKrew/openkrew/ci.yml?branch=main&style=for-the-badge" alt="CI status"></a>
+  <a href="https://github.com/OpenKrew/openkrew/releases"><img src="https://img.shields.io/github/v/release/OpenKrew/openkrew?include_prereleases&style=for-the-badge" alt="GitHub release"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-BSL_1.1-blue.svg?style=for-the-badge" alt="BSL 1.1 License"></a>
+</p>
+
+---
+
+OpenKrew runs named AI agents on different physical machines and lets them work together on projects. Each agent has its own identity, role, and permissions. They coordinate through Slack and a central Hub API.
+
+Most multi-agent frameworks run everything in one process. OpenKrew doesn't. Your agents are actually distributed, each on its own box, talking to each other over real channels. Think less "threads sharing memory" and more "remote coworkers in a Slack workspace."
+
+[Project Vision](PROJECT_VISION.md)
+
+## How it works
+
+```
+Primary Machine (Hub) -- Always On
+├── Agent Registry API (:4000)
+├── Shared Memory DB (PostgreSQL + pgvector)
+├── Task Queue (Redis / BullMQ)
+├── Provisioning Service (SSH)
+└── Agent: "Quinn" -- Dev Lead
+
+Spoke 1 (e.g., MacBook Mini)
+└── Agent: "Morgan" -- Frontend Developer
+
+Spoke 2 (e.g., Linux Server)
+└── Agent: "Reese" -- Infrastructure / DevOps
+```
+
+The Hub runs the registry, shared memory, and task queue. Spokes are remote machines, each running one agent. Agents talk through Slack for conversation and the Hub API for structured handoffs.
+
+## What's in the box
+
+Agents run on separate machines, not threads. Each one has a name, role, and personality defined in YAML. They share a three tier memory system: personal (local files), team (PostgreSQL + pgvector), and project scoped. You set per-agent permissions for shell access, filesystem, git, packages, and secrets.
+
+Slack is the communication layer. Works with Claude, GPT, DeepSeek, Ollama, LM Studio, and others. SSH provisioning handles remote setup. A privilege broker lets agents request elevated access without holding root credentials directly.
+
+## Agent config
+
+Each agent gets a YAML file:
+
+```yaml
+agent:
+  name: Quinn
+  role: dev-lead
+  machine: mac-mini-lan
+  model: claude-opus-4-6
+  teammates:
+    - name: Morgan
+      role: frontend
+      channel: "#frontend"
+    - name: Reese
+      role: infra
+      channel: "#infrastructure"
+  tools: [git, gh, dotnet-cli, docker]
+  mcps: [context7, sequential-thinking]
+```
+
+## Permissions
+
+You control what each agent can do. Morgan here can push code and open PRs but can't merge, can't sudo, and can't touch anything outside the UI and docs folders:
+
+```yaml
+agent: Morgan
+role: frontend
+
+shell:
+  enabled: true
+  sudo: false
+  blocked_commands: [rm -rf /, shutdown, reboot]
+
+filesystem:
+  mode: scoped
+  allowed_paths:
+    - ~/projects/my-app/UI/**
+    - ~/projects/my-app/docs/**
+
+git:
+  push: true
+  create_pr: true
+  merge_pr: false # Only lead can merge
+  force_push: false
+
+packages:
+  install: true
+  managers: [npm, npx]
+
+secrets:
+  access: false
+```
+
+## Memory
+
+| Tier     | Scope           | Storage               | Example                                       |
+| -------- | --------------- | --------------------- | --------------------------------------------- |
+| Personal | One agent       | Local filesystem      | "I prefer TDD"                                |
+| Team     | All agents      | PostgreSQL + pgvector | "API uses .NET 10, frontend is Next.js 14"    |
+| Project  | Current project | Shared DB, scoped     | "Stage 2 of auth migration, blocked on OAuth" |
+
+## Tech stack
+
+| Component        | Technology                                  |
+| ---------------- | ------------------------------------------- |
+| Hub API          | Node.js (Fastify) or .NET, REST + WebSocket |
+| Shared memory    | PostgreSQL + pgvector                       |
+| Task queue       | Redis / BullMQ                              |
+| Agent runtime    | Node.js (Pi agent framework)                |
+| Messaging        | Slack (via Slack Bolt)                      |
+| SSH provisioning | node-ssh                                    |
+| LLM support      | Model agnostic, 12+ providers               |
+
+## Building from source
+
+Needs Node 22.16+ (24 recommended).
+
+```bash
+git clone https://github.com/OpenKrew/openkrew.git
+cd openkrew
+
+pnpm install
+pnpm build
+```
+
+## Roadmap
+
+We're starting with the basics: get two agents talking on one machine, nail the communication and memory protocols. After that, SSH provisioning for actual multi machine setups, then the interactive setup wizard, then the permission system. Agent to agent coordination (handoffs, conflict resolution) comes last. Then we open source it properly.
+
+## Origin
+
+OpenKrew started as a fork of [OpenClaw](https://github.com/openclaw/openclaw) (MIT). We kept the Gateway, Pi agent framework, LLM adapters, and Slack integration. Everything else -- multi machine distribution, shared memory, role based permissions, team coordination -- is new.
+
+See [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md) for attribution.
+
+## License
+
+[Business Source License 1.1](LICENSE) -- free for non-commercial and internal use. Converts to Apache 2.0 after 3 years per version. Commercial licensing available at licensing@openkrew.com.

package/core-bootstrap.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+
+/**
+ * OpenKrew .NET Core Bootstrapper
+ *
+ * Downloads the platform-specific self-contained binary from S3.
+ * Subsequent runs use the cached binary directly.
+ *
+ * This file is invoked by openkrew.mjs when the user runs `openkrew`.
+ */
+
+import { spawn } from "node:child_process";
+import {
+  createWriteStream,
+  existsSync,
+  mkdirSync,
+  chmodSync,
+  readFileSync,
+  writeFileSync,
+  rmSync,
+} from "node:fs";
+import { homedir, platform, arch } from "node:os";
+import { join } from "node:path";
+import { pipeline } from "node:stream/promises";
+
+const OPENKREW_DIR = join(homedir(), ".openkrew");
+const BIN_DIR = join(OPENKREW_DIR, "bin");
+const VERSION_FILE = join(BIN_DIR, ".version");
+const S3_BASE = "https://openkrew-releases.s3.amazonaws.com";
+const PACKAGE_VERSION = (() => {
+  try {
+    const pkg = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8"));
+    return pkg.version;
+  } catch {
+    return "0.1.0";
+  }
+})();
+
+/**
+ * Resolves the platform-specific runtime identifier.
+ */
+function getRuntimeId() {
+  const p = platform();
+  const a = arch();
+
+  const map = {
+    "darwin-arm64": "osx-arm64",
+    "darwin-x64": "osx-x64",
+    "linux-x64": "linux-x64",
+    "linux-arm64": "linux-arm64",
+    "win32-x64": "win-x64",
+    "win32-arm64": "win-arm64",
+  };
+
+  const rid = map[`${p}-${a}`];
+  if (!rid) {
+    throw new Error(
+      `Unsupported platform: ${p}-${a}. OpenKrew supports: macOS (arm64/x64), Linux (x64/arm64), Windows (x64/arm64).`,
+    );
+  }
+  return rid;
+}
+
+/**
+ * Returns the expected binary name for the current platform.
+ */
+function getBinaryName() {
+  return platform() === "win32" ? "OpenKrew.Hub.exe" : "OpenKrew.Hub";
+}
+
+/**
+ * Checks if the binary is already downloaded and matches the expected version.
+ */
+function isInstalled() {
+  const binaryPath = join(BIN_DIR, getBinaryName());
+  if (!existsSync(binaryPath)) return false;
+
+  try {
+    const installedVersion = readFileSync(VERSION_FILE, "utf8").trim();
+    return installedVersion === PACKAGE_VERSION;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Downloads the self-contained binary from S3.
+ */
+async function downloadBinary() {
+  const rid = getRuntimeId();
+  const url = `${S3_BASE}/stable/${rid}/openkrew.tar.gz`;
+
+  process.stderr.write(`\x1b[36mOpenKrew\x1b[0m: downloading ${rid} binary (v${PACKAGE_VERSION})...\n`);
+
+  mkdirSync(BIN_DIR, { recursive: true });
+
+  const response = await fetch(url);
+
+  if (!response.ok) {
+    process.stderr.write(`\x1b[31mError: Failed to download binary (HTTP ${response.status})\x1b[0m\n`);
+    process.stderr.write(`URL: ${url}\n`);
+    process.stderr.write("Try again later or check https://github.com/OpenKrew/openkrew/releases\n");
+    process.exit(1);
+  }
+
+  const tmpFile = join(OPENKREW_DIR, `download-${Date.now()}.tar.gz`);
+
+  try {
+    const fileStream = createWriteStream(tmpFile);
+    await pipeline(response.body, fileStream);
+
+    // Extract
+    const tarProcess = spawn("tar", ["xzf", tmpFile, "-C", BIN_DIR], { stdio: "inherit" });
+    await new Promise((resolve, reject) => {
+      tarProcess.on("close", (code) =>
+        code === 0 ? resolve() : reject(new Error(`tar exited with code ${code}`)),
+      );
+      tarProcess.on("error", reject);
+    });
+
+    // Make binary executable on Unix
+    if (platform() !== "win32") {
+      const binaryPath = join(BIN_DIR, getBinaryName());
+      if (existsSync(binaryPath)) {
+        chmodSync(binaryPath, 0o755);
+      }
+    }
+
+    writeFileSync(VERSION_FILE, PACKAGE_VERSION);
+    process.stderr.write(`\x1b[32mInstalled OpenKrew v${PACKAGE_VERSION}\x1b[0m\n`);
+  } finally {
+    try { rmSync(tmpFile); } catch {}
+  }
+}
+
+/**
+ * Runs the .NET Hub binary, passing through all CLI arguments.
+ */
+function runBinary() {
+  const binaryPath = join(BIN_DIR, getBinaryName());
+
+  if (!existsSync(binaryPath)) {
+    process.stderr.write(`\x1b[31mError: OpenKrew binary not found at ${binaryPath}\x1b[0m\n`);
+    process.exit(1);
+  }
+
+  const child = spawn(binaryPath, process.argv.slice(2), {
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      OPENKREW_BOOTSTRAPPED: "1",
+    },
+  });
+
+  child.on("close", (code) => process.exit(code ?? 0));
+  child.on("error", (err) => {
+    process.stderr.write(`\x1b[31mFailed to start OpenKrew: ${err.message}\x1b[0m\n`);
+    process.exit(1);
+  });
+}
+
+// ── Main ──────────────────────────────────────────────────────────────
+
+export async function bootstrap() {
+  if (!isInstalled()) {
+    await downloadBinary();
+  }
+  runBinary();
+}

package/openkrew.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { access } from "node:fs/promises";
+import module from "node:module";
+import { fileURLToPath } from "node:url";
+
+const MIN_NODE_MAJOR = 22;
+const MIN_NODE_MINOR = 12;
+const MIN_NODE_VERSION = `${MIN_NODE_MAJOR}.${MIN_NODE_MINOR}`;
+
+const parseNodeVersion = (rawVersion) => {
+  const [majorRaw = "0", minorRaw = "0"] = rawVersion.split(".");
+  return {
+    major: Number(majorRaw),
+    minor: Number(minorRaw),
+  };
+};
+
+const isSupportedNodeVersion = (version) =>
+  version.major > MIN_NODE_MAJOR ||
+  (version.major === MIN_NODE_MAJOR && version.minor >= MIN_NODE_MINOR);
+
+const ensureSupportedNodeVersion = () => {
+  if (isSupportedNodeVersion(parseNodeVersion(process.versions.node))) {
+    return;
+  }
+
+  process.stderr.write(
+    `openkrew: Node.js v${MIN_NODE_VERSION}+ is required (current: v${process.versions.node}).\n` +
+      "If you use nvm, run:\n" +
+      `  nvm install ${MIN_NODE_MAJOR}\n` +
+      `  nvm use ${MIN_NODE_MAJOR}\n` +
+      `  nvm alias default ${MIN_NODE_MAJOR}\n`,
+  );
+  process.exit(1);
+};
+
+ensureSupportedNodeVersion();
+
+// https://nodejs.org/api/module.html#module-compile-cache
+if (module.enableCompileCache && !process.env.NODE_DISABLE_COMPILE_CACHE) {
+  try {
+    module.enableCompileCache();
+  } catch {
+    // Ignore errors
+  }
+}
+
+// ── OpenKrew .NET Core Bootstrap ──────────────────────────────────────
+// The primary runtime is the .NET core platform. The bootstrapper handles
+// downloading, caching, and running the self-contained binary.
+// Falls back to the legacy TypeScript gateway if the bootstrap fails.
+
+const isLegacyMode = process.argv.includes("--legacy") || process.env.OPENKREW_LEGACY === "1";
+
+if (!isLegacyMode) {
+  try {
+    const { bootstrap } = await import("./core-bootstrap.mjs");
+    await bootstrap();
+    // bootstrap() calls process.exit() via the spawned child, so we
+    // only reach here if something went wrong.
+  } catch (err) {
+    // If the .NET bootstrapper fails (no release, no SDK, etc.),
+    // fall through to the legacy TypeScript gateway with a warning.
+    process.stderr.write(
+      `\x1b[33mOpenKrew .NET core unavailable: ${err.message}\x1b[0m\n` +
+        "Falling back to legacy TypeScript gateway.\n" +
+        "Run with OPENKREW_LEGACY=1 to skip this check.\n\n",
+    );
+  }
+}
+
+// ── Legacy TypeScript Gateway (OpenClaw fork) ─────────────────────────
+
+const isModuleNotFoundError = (err) =>
+  err && typeof err === "object" && "code" in err && err.code === "ERR_MODULE_NOT_FOUND";
+
+const isDirectModuleNotFoundError = (err, specifier) => {
+  if (!isModuleNotFoundError(err)) {
+    return false;
+  }
+
+  const expectedUrl = new URL(specifier, import.meta.url);
+  if ("url" in err && err.url === expectedUrl.href) {
+    return true;
+  }
+
+  const message = "message" in err && typeof err.message === "string" ? err.message : "";
+  const expectedPath = fileURLToPath(expectedUrl);
+  return (
+    message.includes(`Cannot find module '${expectedPath}'`) ||
+    message.includes(`Cannot find module "${expectedPath}"`)
+  );
+};
+
+const installProcessWarningFilter = async () => {
+  for (const specifier of ["./dist/warning-filter.js", "./dist/warning-filter.mjs"]) {
+    try {
+      const mod = await import(specifier);
+      if (typeof mod.installProcessWarningFilter === "function") {
+        mod.installProcessWarningFilter();
+        return;
+      }
+    } catch (err) {
+      if (isDirectModuleNotFoundError(err, specifier)) {
+        continue;
+      }
+      throw err;
+    }
+  }
+};
+
+const tryImport = async (specifier) => {
+  try {
+    await import(specifier);
+    return true;
+  } catch (err) {
+    if (isDirectModuleNotFoundError(err, specifier)) {
+      return false;
+    }
+    throw err;
+  }
+};
+
+const exists = async (specifier) => {
+  try {
+    await access(new URL(specifier, import.meta.url));
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const buildMissingEntryErrorMessage = async () => {
+  const lines = ["openkrew: missing dist/entry.(m)js (build output)."];
+  if (!(await exists("./src/entry.ts"))) {
+    return lines.join("\n");
+  }
+
+  lines.push("This install looks like an unbuilt source tree or GitHub source archive.");
+  lines.push(
+    "Build locally with `pnpm install && pnpm build`, or install a built package instead.",
+  );
+  lines.push(
+    "For pinned GitHub installs, use `npm install -g github:openkrew/openkrew#<ref>` instead of a raw `/archive/<ref>.tar.gz` URL.",
+  );
+  lines.push("For releases, use `npm install -g openkrew@latest`.");
+  return lines.join("\n");
+};
+
+const isBareRootHelpInvocation = (argv) =>
+  argv.length === 3 && (argv[2] === "--help" || argv[2] === "-h");
+
+const loadPrecomputedRootHelpText = () => {
+  try {
+    const raw = readFileSync(new URL("./dist/cli-startup-metadata.json", import.meta.url), "utf8");
+    const parsed = JSON.parse(raw);
+    return typeof parsed?.rootHelpText === "string" && parsed.rootHelpText.length > 0
+      ? parsed.rootHelpText
+      : null;
+  } catch {
+    return null;
+  }
+};
+
+const tryOutputBareRootHelp = async () => {
+  if (!isBareRootHelpInvocation(process.argv)) {
+    return false;
+  }
+  const precomputed = loadPrecomputedRootHelpText();
+  if (precomputed) {
+    process.stdout.write(precomputed);
+    return true;
+  }
+  for (const specifier of ["./dist/cli/program/root-help.js", "./dist/cli/program/root-help.mjs"]) {
+    try {
+      const mod = await import(specifier);
+      if (typeof mod.outputRootHelp === "function") {
+        mod.outputRootHelp();
+        return true;
+      }
+    } catch (err) {
+      if (isDirectModuleNotFoundError(err, specifier)) {
+        continue;
+      }
+      throw err;
+    }
+  }
+  return false;
+};
+
+if (await tryOutputBareRootHelp()) {
+  // OK
+} else {
+  await installProcessWarningFilter();
+  if (await tryImport("./dist/entry.js")) {
+    // OK
+  } else if (await tryImport("./dist/entry.mjs")) {
+    // OK
+  } else {
+    throw new Error(await buildMissingEntryErrorMessage());
+  }
+}

package/package.json

@@ -1,12 +1,40 @@
 {
   "name": "openkrew",
-  "version": "0.0.1",
-  "description": "OpenKrew: AI agents on separate machines, working as a team.",
-  "license": "MIT",
+  "version": "0.1.2",
+  "description": "Distributed multi-machine AI agent team platform",
+  "type": "module",
+  "license": "BUSL-1.1",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/OpenKrew/openkrew.git"
+    "url": "https://github.com/OpenKrew/openkrew"
   },
-  "homepage": "https://github.com/OpenKrew/openkrew",
-  "keywords": ["ai", "agents", "distributed", "multi-agent", "slack", "llm"]
+  "homepage": "https://openkrew.com",
+  "bin": {
+    "openkrew": "./openkrew.mjs"
+  },
+  "files": [
+    "openkrew.mjs",
+    "core-bootstrap.mjs",
+    "scripts/check-global.mjs",
+    "LICENSE"
+  ],
+  "scripts": {
+    "preinstall": "node scripts/check-global.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "multi-agent",
+    "distributed",
+    "slack",
+    "discord",
+    "teams",
+    "llm",
+    "claude",
+    "openai",
+    "developer-tools"
+  ]
 }

package/scripts/check-global.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+if (process.env.npm_config_global !== "true") {
+  console.error("\n  OpenKrew must be installed globally:\n");
+  console.error("    npm install -g openkrew\n");
+  process.exit(1);
+}