mop-agent 0.1.0

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "mop-agent",
+  "version": "0.1.0",
+  "description": "Self-hosted AI brain and control plane for MOP-FLOW projects, installed with npx mop-agent.",
+  "author": "BURHANDEV ENTERPRISE",
+  "license": "UNLICENSED",
+  "keywords": [
+    "ai",
+    "agent",
+    "memory",
+    "self-hosted",
+    "mop-flow"
+  ],
+  "homepage": "https://github.com/BURHANDEV-ENTERPRISE/mop-agent#readme",
+  "bugs": {
+    "url": "https://github.com/BURHANDEV-ENTERPRISE/mop-agent/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BURHANDEV-ENTERPRISE/mop-agent.git"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "workspaces": [
+    "packages/*",
+    "apps/*"
+  ],
+  "bin": {
+    "mop-agent": "installer/bootstrap.mjs"
+  },
+  "files": [
+    "apps/web/app",
+    "apps/web/bin",
+    "apps/web/lib",
+    "apps/web/scripts",
+    "apps/web/.env.example",
+    "apps/web/next-env.d.ts",
+    "apps/web/next.config.mjs",
+    "apps/web/package.json",
+    "apps/web/server.ts",
+    "apps/web/tsconfig.json",
+    "packages/flow-connector/bin",
+    "packages/flow-connector/src",
+    "packages/flow-connector/package.json",
+    "packages/flow-connector/tsconfig.json",
+    "packages/link-protocol/src",
+    "packages/link-protocol/package.json",
+    "packages/link-protocol/tsconfig.json",
+    "installer/bootstrap.mjs",
+    "installer/lib.mjs",
+    "installer/mop-agent.mjs",
+    "npm-shrinkwrap.json",
+    "tsconfig.base.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "npm run build --workspaces --if-present",
+    "typecheck": "npm run typecheck --workspaces --if-present",
+    "dev:web": "npm run dev --workspace @mop/web",
+    "dev:flow": "npm run dev --workspace @mop/flow-connector",
+    "installer": "node installer/mop-agent.mjs",
+    "bootstrap:self-test": "node installer/bootstrap.mjs --self-test",
+    "release:check": "npm run typecheck && npx tsx scripts/smoke-installer.mts && npm run bootstrap:self-test",
+    "prepublishOnly": "npm run release:check",
+    "clean": "node -e \"console.log('clean: remove dist + node_modules manually if needed')\""
+  }
+}

package/packages/flow-connector/bin/cli.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * Dev CLI for the FLOW connector. Cross-platform (Node only).
+ *
+ *   mop-flow-dev link  --url <agentUrl> --code <code> --project <id> [--root <dir>]
+ *   mop-flow-dev serve [--root <dir>]
+ *
+ * In production this folds into the published `mop-flow` binary (1.3.0).
+ */
+import { pair } from "../src/pair.js";
+import { serve } from "../src/serve.js";
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (!a.startsWith("--")) {
+      out._.push(a);
+      continue;
+    }
+    const key = a.slice(2);
+    const next = argv[i + 1];
+    if (!next || next.startsWith("--")) {
+      out[key] = true;
+    } else {
+      out[key] = next;
+      i += 1;
+    }
+  }
+  return out;
+}
+
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const args = parseArgs(rest);
+  const root = typeof args.root === "string" ? args.root : process.cwd();
+
+  if (cmd === "link") {
+    if (!args.url || !args.code || !args.project) {
+      console.error("usage: mop-flow-dev link --url <agentUrl> --code <code> --project <id> [--root <dir>]");
+      process.exit(1);
+    }
+    const link = await pair({
+      projectRoot: root,
+      agentUrl: String(args.url),
+      code: String(args.code),
+      projectId: String(args.project),
+      name: typeof args.name === "string" ? args.name : undefined,
+    });
+    console.log(`linked: project=${link.projectId} → ${link.agentUrl}`);
+    console.log(`wrote ${root}/.MOP/link.json (token stored, gitignored)`);
+    return;
+  }
+
+  if (cmd === "serve") {
+    await serve({ projectRoot: root });
+    return;
+  }
+
+  console.error("commands: link | serve");
+  process.exit(1);
+}
+
+main().catch((e) => {
+  console.error(e instanceof Error ? e.message : e);
+  process.exit(1);
+});

package/packages/flow-connector/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@mop/flow-connector",
+  "version": "0.0.1",
+  "description": "MOP-FLOW vNext connector — dials out to MOP-AGENT, serves project context, feeds the Brain. (Dev home; merges into published mop-flow later.)",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "bin": {
+    "mop-flow-dev": "./bin/cli.mjs"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "dev": "tsx watch src/serve.ts",
+    "link": "tsx bin/cli.mjs link",
+    "serve": "tsx bin/cli.mjs serve"
+  },
+  "dependencies": {
+    "@mop/link-protocol": "*",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.12",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  }
+}

package/packages/flow-connector/src/exec.ts

@@ -0,0 +1,81 @@
+/**
+ * Execution backends for capability-gated run_shell (Fasa 6).
+ *
+ *  host   — run on the user's machine (default), cwd = project root.
+ *  docker — sandbox in a container; project mounted at /work; network "none" by default.
+ *  ssh    — run on a remote build box.
+ *
+ * Only reached when the runShell/editCode capability is enabled (tools.ts guards),
+ * so this is opt-in. Each command has a hard timeout.
+ */
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
+import type { ExecutionPolicy } from "@mop/link-protocol";
+
+export type ExecResult = { stdout: string; stderr: string; code: number | null };
+
+function run(cmd: string, args: string[], timeoutMs: number): Promise<ExecResult> {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { windowsHide: true });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => {
+      stderr += `\n[timeout after ${timeoutMs}ms]`;
+      child.kill("SIGKILL");
+    }, timeoutMs);
+    child.stdout.on("data", (d) => (stdout += d.toString()));
+    child.stderr.on("data", (d) => (stderr += d.toString()));
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      resolve({ stdout, stderr: stderr + String(e.message), code: 127 });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ stdout: stdout.slice(0, 100_000), stderr: stderr.slice(0, 20_000), code });
+    });
+  });
+}
+
+export async function runShell(command: string, projectRoot: string, policy: ExecutionPolicy): Promise<ExecResult> {
+  const timeoutMs = policy.timeoutMs ?? 60_000;
+
+  if (policy.backend === "docker") {
+    const image = policy.docker?.image ?? "node:20-slim";
+    const network = policy.docker?.network ?? "none";
+    return run(
+      "docker",
+      ["run", "--rm", "--network", network, "-v", `${projectRoot}:/work`, "-w", "/work", image, "sh", "-lc", command],
+      timeoutMs,
+    );
+  }
+
+  if (policy.backend === "ssh") {
+    if (!policy.ssh) return { stdout: "", stderr: "ssh backend not configured", code: 1 };
+    const remote = `${policy.ssh.user}@${policy.ssh.host}`;
+    const remoteCmd = policy.ssh.cwd ? `cd ${policy.ssh.cwd} && ${command}` : command;
+    return run("ssh", [remote, remoteCmd], timeoutMs);
+  }
+
+  // host (default)
+  const shell = platform() === "win32" ? "cmd" : "sh";
+  const flag = platform() === "win32" ? "/c" : "-lc";
+  return new Promise((resolve) => {
+    const child = spawn(shell, [flag, command], { cwd: projectRoot, windowsHide: true });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => {
+      stderr += `\n[timeout after ${timeoutMs}ms]`;
+      child.kill("SIGKILL");
+    }, timeoutMs);
+    child.stdout.on("data", (d) => (stdout += d.toString()));
+    child.stderr.on("data", (d) => (stderr += d.toString()));
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      resolve({ stdout, stderr: stderr + String(e.message), code: 127 });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ stdout: stdout.slice(0, 100_000), stderr: stderr.slice(0, 20_000), code });
+    });
+  });
+}

package/packages/flow-connector/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @mop/flow-connector — MOP-FLOW vNext connector.
+ *
+ * Public surface for embedding the connector (e.g. inside the published mop-flow,
+ * or for tests that drive the link end-to-end).
+ */
+export { pair, type PairOptions } from "./pair.js";
+export { serve, type ServeOptions } from "./serve.js";
+export { buildSnapshot, redactSensitive } from "./snapshot.js";
+export { handleToolRequest, CapabilityError, type ToolContext } from "./tools.js";
+export {
+  readLink,
+  writeLink,
+  isLinked,
+  linkPath,
+  type LinkFile,
+} from "./linkfile.js";

package/packages/flow-connector/src/linkfile.ts

@@ -0,0 +1,46 @@
+/**
+ * .MOP/link.json read/write — the per-project link credential + config.
+ * The bearer token lives ONLY here (gitignored, chmod 600 on POSIX).
+ */
+import { readFile, writeFile, chmod, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { Capabilities, ExecutionPolicy } from "@mop/link-protocol";
+
+export type LinkFile = {
+  schemaVersion: "1.0";
+  agentUrl: string;
+  wsUrl: string;
+  projectId: string;
+  linkToken: string;
+  capabilities: Capabilities;
+  /** Only used when runShell/editCode capabilities are enabled. */
+  execution?: ExecutionPolicy;
+  lastSyncAt: string | null;
+  autoSync: boolean;
+};
+
+export function linkPath(projectRoot: string): string {
+  return join(projectRoot, ".MOP", "link.json");
+}
+
+export function isLinked(projectRoot: string): boolean {
+  return existsSync(linkPath(projectRoot));
+}
+
+export async function readLink(projectRoot: string): Promise<LinkFile> {
+  const raw = await readFile(linkPath(projectRoot), "utf8");
+  return JSON.parse(raw) as LinkFile;
+}
+
+export async function writeLink(projectRoot: string, link: LinkFile): Promise<void> {
+  const p = linkPath(projectRoot);
+  await mkdir(dirname(p), { recursive: true });
+  await writeFile(p, JSON.stringify(link, null, 2), "utf8");
+  // Best-effort restrictive perms on POSIX; on Windows this is a no-op.
+  try {
+    await chmod(p, 0o600);
+  } catch {
+    /* Windows / unsupported FS — file is gitignored regardless */
+  }
+}

package/packages/flow-connector/src/pair.ts

@@ -0,0 +1,66 @@
+/**
+ * Pairing — FLOW -> AGENT (HTTP), before the WSS link opens.
+ * Posts the project manifest + one-time pairing code, receives a link token.
+ */
+import { platform } from "node:os";
+import {
+  DEFAULT_CAPABILITIES,
+  type Capabilities,
+  type PairRequest,
+  type PairResponse,
+  type ProjectManifest,
+} from "@mop/link-protocol";
+import { writeLink, type LinkFile } from "./linkfile.js";
+
+export type PairOptions = {
+  projectRoot: string;
+  agentUrl: string;
+  code: string;
+  projectId: string;
+  name?: string;
+  mopFlowVersion?: string;
+  capabilities?: Capabilities;
+};
+
+function deriveWsUrl(agentUrl: string): string {
+  const u = new URL(agentUrl);
+  u.protocol = u.protocol === "https:" ? "wss:" : "ws:";
+  u.pathname = "/link";
+  return u.toString();
+}
+
+export async function pair(opts: PairOptions): Promise<LinkFile> {
+  const manifest: ProjectManifest = {
+    projectId: opts.projectId,
+    name: opts.name ?? opts.projectId,
+    mopFlowVersion: opts.mopFlowVersion ?? "1.3.0-dev",
+    platform: platform(),
+    capabilities: opts.capabilities ?? DEFAULT_CAPABILITIES,
+  };
+
+  const body: PairRequest = { code: opts.code, manifest };
+  const res = await fetch(new URL("/api/link/pair", opts.agentUrl), {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`pair_failed:${res.status}:${text}`);
+  }
+
+  const out = (await res.json()) as PairResponse;
+  const link: LinkFile = {
+    schemaVersion: "1.0",
+    agentUrl: opts.agentUrl,
+    wsUrl: out.wsUrl ?? deriveWsUrl(opts.agentUrl),
+    projectId: out.projectId,
+    linkToken: out.linkToken,
+    capabilities: manifest.capabilities,
+    lastSyncAt: null,
+    autoSync: true,
+  };
+  await writeLink(opts.projectRoot, link);
+  return link;
+}

package/packages/flow-connector/src/serve.ts

@@ -0,0 +1,103 @@
+/**
+ * Reverse WSS client — FLOW dials OUT to AGENT and keeps the link open.
+ *
+ * Outbound connection traverses NAT/firewall, so the AGENT can live on a VPS while
+ * the project stays on the user's PC. Auto-reconnect with exponential backoff
+ * handles laptop sleep / network changes (Windows + Linux).
+ */
+import WebSocket from "ws";
+import {
+  parseLinkMessage,
+  type Capabilities,
+  type LinkMessage,
+  type McpToolName,
+} from "@mop/link-protocol";
+import { readLink, writeLink } from "./linkfile.js";
+import { buildSnapshot } from "./snapshot.js";
+import { handleToolRequest, type ToolContext } from "./tools.js";
+
+export type ServeOptions = {
+  projectRoot: string;
+  /** optional hook into the real .MOP session model (v1.2.0) */
+  hasValidSession?: ToolContext["hasValidSession"];
+  onStatus?: (s: string) => void;
+};
+
+const MAX_BACKOFF = 30_000;
+
+export async function serve(opts: ServeOptions): Promise<void> {
+  const log = opts.onStatus ?? ((s: string) => console.log(`[mop-flow] ${s}`));
+  let backoff = 1_000;
+  let stopped = false;
+
+  const connect = async (): Promise<void> => {
+    const link = await readLink(opts.projectRoot);
+    const ctx: ToolContext = {
+      projectRoot: opts.projectRoot,
+      capabilities: link.capabilities,
+      hasValidSession: opts.hasValidSession,
+      execution: link.execution,
+    };
+
+    const ws = new WebSocket(link.wsUrl, {
+      headers: { Authorization: `Bearer ${link.linkToken}` },
+    });
+
+    ws.on("open", async () => {
+      backoff = 1_000;
+      const snap = await buildSnapshot(opts.projectRoot, link.projectId);
+      ws.send(JSON.stringify(snap));
+      link.lastSyncAt = new Date().toISOString();
+      await writeLink(opts.projectRoot, link);
+      log(`linked → ${link.wsUrl} · snapshot pushed (${snap.memory.length} memories)`);
+    });
+
+    ws.on("message", async (raw) => {
+      let msg: LinkMessage;
+      try {
+        msg = parseLinkMessage(raw.toString());
+      } catch {
+        return;
+      }
+      if (msg.t === "req") {
+        try {
+          const data = await handleToolRequest(msg.tool as McpToolName, msg.args, ctx);
+          ws.send(JSON.stringify({ t: "res", id: msg.id, ok: true, data }));
+        } catch (e) {
+          ws.send(JSON.stringify({ t: "res", id: msg.id, ok: false, error: errMsg(e) }));
+        }
+      } else if (msg.t === "ping") {
+        ws.send(JSON.stringify({ t: "pong" }));
+      } else if (msg.t === "hello") {
+        log(`hello from AGENT (caps: ${capSummary(msg.capabilities)})`);
+      }
+    });
+
+    ws.on("close", () => {
+      if (stopped) return;
+      log(`link closed · retry in ${backoff}ms`);
+      setTimeout(connect, backoff);
+      backoff = Math.min(backoff * 2, MAX_BACKOFF);
+    });
+
+    ws.on("error", (e) => log(`ws error: ${errMsg(e)}`));
+  };
+
+  process.on("SIGINT", () => {
+    stopped = true;
+    process.exit(0);
+  });
+
+  await connect();
+}
+
+function errMsg(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+function capSummary(caps: Capabilities): string {
+  return Object.entries(caps)
+    .filter(([, v]) => v)
+    .map(([k]) => k)
+    .join(",");
+}

package/packages/flow-connector/src/snapshot.ts

@@ -0,0 +1,94 @@
+/**
+ * Snapshot builder — gathers project state + memory + artifacts to push to the Brain.
+ *
+ * Privacy at source: secrets (tokens, password hashes) are stripped BEFORE the
+ * snapshot leaves the machine. The Brain stores experience, never credentials.
+ */
+import { readFile, readdir, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { ArtifactRef, MemoryEntry, SnapshotPushMessage } from "@mop/link-protocol";
+
+const SENSITIVE_KEY = /(token|secret|password|passwordhash|apikey|api_key)/i;
+
+/** Recursively strip values whose key looks sensitive. */
+export function redactSensitive<T>(value: T): T {
+  if (Array.isArray(value)) {
+    return value.map((v) => redactSensitive(v)) as unknown as T;
+  }
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      if (SENSITIVE_KEY.test(k)) continue;
+      out[k] = redactSensitive(v);
+    }
+    return out as unknown as T;
+  }
+  return value;
+}
+
+async function readState(projectRoot: string): Promise<unknown> {
+  const p = join(projectRoot, ".MOP", "STATE.json");
+  if (!existsSync(p)) return {};
+  return JSON.parse(await readFile(p, "utf8"));
+}
+
+/** Read recent episodic entries from monthly JSONL files (.MOP/memory/YYYY-MM.jsonl). */
+async function readMemory(projectRoot: string, limit = 200): Promise<MemoryEntry[]> {
+  const dir = join(projectRoot, ".MOP", "memory");
+  if (!existsSync(dir)) return [];
+  const files = (await readdir(dir))
+    .filter((f) => f.endsWith(".jsonl"))
+    .sort()
+    .reverse();
+
+  const entries: MemoryEntry[] = [];
+  for (const f of files) {
+    const raw = await readFile(join(dir, f), "utf8");
+    for (const line of raw.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        entries.push(JSON.parse(trimmed) as MemoryEntry);
+      } catch {
+        /* skip malformed line */
+      }
+    }
+    if (entries.length >= limit) break;
+  }
+  return entries.slice(0, limit);
+}
+
+async function listArtifacts(projectRoot: string): Promise<ArtifactRef[]> {
+  const dir = join(projectRoot, ".MOP", "artifacts");
+  if (!existsSync(dir)) return [];
+  const out: ArtifactRef[] = [];
+  const walk = async (d: string, base: string): Promise<void> => {
+    for (const name of await readdir(d)) {
+      const full = join(d, name);
+      const s = await stat(full);
+      if (s.isDirectory()) await walk(full, join(base, name));
+      else out.push({ path: join(base, name), updatedAt: s.mtimeMs });
+    }
+  };
+  await walk(dir, "");
+  return out;
+}
+
+export async function buildSnapshot(
+  projectRoot: string,
+  projectId: string,
+): Promise<SnapshotPushMessage> {
+  const [state, memory, artifacts] = await Promise.all([
+    readState(projectRoot),
+    readMemory(projectRoot),
+    listArtifacts(projectRoot),
+  ]);
+  return {
+    t: "snapshot.push",
+    projectId,
+    state: redactSensitive(state),
+    memory,
+    artifacts,
+  };
+}